Swagger Inspectorを使用して既存APIのOpen API Specificationを作成する

Swaggerを使用してAPIの仕様書を作成する際、Swagger EditorやStoplight Studioを使用する選択肢などが考えられます。
新規APIの場合はそれらを使用し０から作成する必要がありますが、既存APIの場合Swagger Inspectorを使用することである程度の仕様を反映させた仕様書を自動生成することができます。

現在の業務で「SwaggerHubを使用した既存APIのドキュメント化」を行う必要があるのですが、「１からすべて作成していくのが面倒・・・」と思い探していたところこちらのツールを発見し、試してみました。

【注意】APIの公開設定について

今回はSwaggerHubの無料プランを使用していますが、APIの公開設定はPublicしか選択することができません。
Privateを選択するにはTeamプラン以上を登録する必要があるため、注意が必要です。

既存APIから仕様書作成の流れ

1.Swagger Inspectorにログイン
2.APIを実行
3.SwaggerHub上で表示

1. Swagger Inspectorにログイン

はじめにSwaggaer Inspectorのページを表示し、右上の「LOG IN」からログインします。

2. APIを実行

実際にAPIを実行してみます。
今回はJSONPlaceholderのユーザー取得とユーザー登録APIを実行します。
基本的にはPOSTMANのようなAPIテストツールと同様の使い方ができます。

会員取得API

会員登録API

3. SwaggerHub上で表示

実行したAPIはHistory欄に追加されます。
仕様書を作成したいAPIをチェックボックスで選択し、「CREATE API DEFINITION」を選択します。

「GO TO SWAGGERHUB」をクリックします。

作成する仕様書のタイトル入力や、公開設定を選択します。
SwaggerHubのfreeプランではAPIを非公開にすることはできません。

仕様書が生成されていることが確認できます。

openapi: 3.0.1
info:
  title: defaultTitle
  description: defaultDescription
  version: '0.1'
servers:
  - url: https://jsonplaceholder.typicode.com
paths:
  /posts/1:
    get:
      description: Auto generated using Swagger Inspector
      responses:
        '200':
          description: Auto generated using Swagger Inspector
          content:
            application/json; charset=utf-8:
              schema:
                type: string
              examples: {}
      servers:
        - url: https://jsonplaceholder.typicode.com
    servers:
      - url: https://jsonplaceholder.typicode.com
  /posts:
    post:
      description: Auto generated using Swagger Inspector
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties: {}
            examples:
              '0':
                value: |-
                  [
                      {
                          "title": "a1 test",
                          "body": "this is test by a1",
                          "userId": 1
                      }
                  ]
      responses:
        '201':
          description: Auto generated using Swagger Inspector
          content:
            application/json; charset=utf-8:
              schema:
                type: string
              examples: {}
      servers:
        - url: https://jsonplaceholder.typicode.com
    servers:
      - url: https://jsonplaceholder.typicode.com

まとめ

Swagger Inspectorを使用して既存APIのOpen API Specificationを作成しました。
Schemaを別途設定したり、他の項目についても追加する必要はありますが、ある程度のパラメータやレスポンスは自動で生成してくれます。
1から自分で書くよりは非常に楽なので、今後も使用していきたいと思います。