Apidog

オールインワン協働API開発プラットフォーム

API設計

APIドキュメント

APIデバッグ

APIモック

API自動テスト

解決済み:Swaggerとは?日本語化されるのは可能?

API開発のプロセス中に、Swaggerに触れることが多いと思います。本文では、Swaggerの詳細を解説した上、Swaggerの日本語化について皆さんに紹介します。

中村 拓也

中村 拓也

Updated on 11月 12, 2024

解決済み:

Swaggerとは?

Swaggerは、一般的な意味が以下のように、2つあります。

  • SmartBear SoftwareのAPI開発者向けのツールスイートです。
  • OpenAPI仕様の基礎となっている以前の仕様で、Swagger仕様とも言えます。
Swagger UIの仕様書のイメージ

Swaggerツール

Swagger(またはOpenAPI)のツールは、APIの設計、ドキュメント化、テスト、モック作成、コード生成など、さまざまな目的で使用されます。以下にいくつかの一般的なSwaggerツールを挙げます。

  • Swagger Editor: Swaggerの仕様書を編集し、即座にプレビューできるオンラインエディタです。
  • Swagger UI: Swaggerの仕様書をユーザーフレンドリーなHTMLドキュメントとして表示するためのツールです。
  • Swagger Codegen: Swaggerの仕様書からクライアントコードやサーバーのスタブを生成するツールです。
  • Swagger Inspector: APIのテストとデバッグを支援するためのツールです。リクエストを作成し、レスポンスを確認することができます。
  • SwaggerHub: Swaggerの仕様書を管理、共有、ホストするためのプラットフォームです。チームでの共同作業やバージョン管理に便利です。

つまり、Swaggerのツールスイートを使って、Swagger仕様書や定義書を作成したり、編集したり、閲覧したりすることができるということです。

Swaggerを日本語化するのは可能?

いずれかのSwaggerツールは日本語をサポートしていません。現時点では、英語のUIしか使えません。それに、日本語に対応する予定があるということを聞いたことがありませんので、近い未来に日本語化されたSwaggerを利用することを期待しないようにしましょう。そこで、英語がそんなに得意ではない方にとって、Swaggerを使って、Swagger仕様書や定義書を作成したり、編集したりすることが難しいのではありません。

ただし、ここで注意を払っていただくのは、全てのSwagger系のツールのUIは日本語をサポートしないことです。Swagger仕様に従うAPIの定義書については、自分で日本語を入力して作成することができます。例えば、Swagger仕様書は、YAMLフォーマットに対応できるので、次のようなYAML形式のコードをSwaggerのツールに導入すると、日本語のSwagger定義書を作成できます。

yamlCopy codeopenapi: 3.0.0
info:
  title: APIのサンプル
  description: 解説用のAPIサンプル
  version: 1.0.0
servers:
  - url: http://localhost:8080
paths:
  /users:
    get:
      summary: ユーザーリストの取得
      description: すへてのユーザーを含むリストを取得します。
      responses:
        '200':
          description: ユーザーリストの取得
          content:
            application/json:
              schema:
                type: array
                items:
                  type: object
                  properties:
                    id:
                      type: integer
                    name:
                      type: string
                    email:
                      type: string
                      format: email

日本語化のSwaggerツール:Apidog

Apidogは、APIに開発におけるチームの協同作業の効率を高めるために開発されていて、APIの設計、開発、テスト、管理、仕様書生成や APIモックなどのことが実現され、今までにない包括的なAPIツールです。つまり、Apidogは、Swagger( OpenAPI)仕様に完璧互換しており、SwaggerツールのSwagger UI、Swagger Editor、Swagger Codegen、Swagger Inspectorの全機能を搭載しています。

button
Apidog

Swagger系のツールからApidogに切り替えるのも超簡単!

ApidogはOpenAPI(Swagger)の仕様をサポートしています。そこで、 Swaggerツールで肝心なデータがあれば、それを直接にApidogにインポートして、シームレスに作業を進むことができるのでしょう。

OpenAPIファイルをApidogにインポートする

SwaggerでAPIを設計して仕様書を生成する

ステップ⒈新しいタブで 新しいAPI をクリックしてエンドポイントを作成します。

APIを設計して仕様書を生成するステップ1

ステップ⒉自分のニーズによって、APIのパスと名前などの情報を設定した上、パラメータを自分で設定します。

APIを設計して仕様書を生成するステップ2

ステップ⒊画面を下にドラッグしたら、Responseのデータ構造を定義することができます。ここで自分で設定することもできますし、現存のSchemaを直接に参照することもできます。

APIを設計して仕様書を生成するステップ3

ステップ⒋ここでResponseの例を追加します。「例を追加」ボタンをクリックすると、新しいウィンドウで「自動生成」をクリックすると、設定したResponseのデータ構造に従って、内蔵のモックルールによってレスポンス例を自動生成するので、とても便利です。

APIを設計して仕様書を生成するステップ4

ここで新しいAPIの作成が完了しました。ここまでは非常にうまくいけるAPIを成功に設計しました。この後、このAPIをチームメンバーに共有したい場合、Apidogの共有機能を使って、非常に直感的なAPIドキュメントを生成して、共有できます。

button
ApidogでバックエンドAPI開発の効率をどう向上させるか?チュートリアル

ApidogでバックエンドAPI開発の効率をどう向上させるか?

ApidogはAPI管理の全体的なソリューションを提供し、定義からデバッグ、ドキュメント作成までバックエンド開発を最適化します。プロジェクトの規模に関わらず、開発者が効率的に作業を完了するのを支援します。

中村 拓也

11月 25, 2024

APIテスト効率化:ApidogでのJSONレスポンス管理法チュートリアル

APIテスト効率化:ApidogでのJSONレスポンス管理法

この記事では、ApidogでJSONレスポンスからアサーション設定、変数抽出、JSONパスのコピー方法を解説しました。APIテストの自動化と効率的なレスポンス検証が簡単になり、データの再利用も可能です。Apidogを使い、API機能を確認しましょう。

中村 拓也

11月 20, 2024

ApidogとAlgolia統合で実現する効率的なドキュメント検索チュートリアル

ApidogとAlgolia統合で実現する効率的なドキュメント検索

本記事は、AlgoliaをApidogと統合し、APIドキュメントの検索機能を改善する方法を紹介します。最適な検索設定を維持しながら、情報アクセスの迅速さと効率性を向上させ、ユーザー体験を向上させます。

中村 拓也

11月 19, 2024