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

解決済み：

Swaggerとは？

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

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

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の全機能を搭載しています。

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

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

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

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

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

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

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

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