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

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

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

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

https://swagger.io/tools/swaggerhub/pricing/

# 既存APIから仕様書作成の流れ
[1.Swagger Inspectorにログイン](#1-Swagger　Inspectorにログイン)
[2.APIを実行](#2-APIを実行)
[3.SwaggerHub上で表示](#3-内容ろ)

# 1. Swagger Inspectorにログイン
はじめに[Swaggaer Inspector](https://inspector.swagger.io/builder)のページを表示し、右上の「LOG IN」からログインします。

![スクリーンショット 2022-09-18 20.45.20.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/637441/88a80a29-846e-56e1-a2e5-b57923aceb80.png)

# 2. APIを実行
実際にAPIを実行してみます。
今回は[JSONPlaceholder](https://jsonplaceholder.typicode.com/)のユーザー取得とユーザー登録APIを実行します。
基本的にはPOSTMANのようなAPIテストツールと同様の使い方ができます。

### 会員取得API
![スクリーンショット 2022-09-18 21.38.05.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/637441/5b2450b2-62e4-ec1f-a354-d13b5be41db2.png)

### 会員登録API
![スクリーンショット 2022-09-18 21.40.01.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/637441/cffa44aa-9cb1-d302-5888-823793ed97b1.png)

# 3. SwaggerHub上で表示
![スクリーンショット 2022-09-18 21.41.40.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/637441/669c2607-31b1-81fe-c064-fe5e55d7074d.png)
実行したAPIはHistory欄に追加されます。
仕様書を作成したいAPIをチェックボックスで選択し、「CREATE API DEFINITION」を選択します。

![スクリーンショット 2022-09-18 21.43.12.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/637441/340526b2-bd40-592a-9108-63daf9d52b53.png)
「GO TO SWAGGERHUB」をクリックします。

![スクリーンショット 2022-09-18 21.45.39.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/637441/8c5f1c9d-b14a-6725-1749-3a106c729226.png)
作成する仕様書のタイトル入力や、公開設定を選択します。
SwaggerHubのfreeプランではAPIを非公開にすることはできません。

![スクリーンショット 2022-09-18 21.48.15.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/637441/a0121282-b2ca-315b-9abb-b9bf39557580.png)
仕様書が生成されていることが確認できます。
```yaml
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から自分で書くよりは非常に楽なので、今後も使用していきたいと思います。