Swagger Viewer で OpenAPI定義を書く

2022.8.25

実践と知見

フロントエンドエンジニアの茶木です。

今までは、OpenAPIの定義ファイルは、Stoplight Studio を介して書くことが多かったのですが、なんやかんやで手書きをする必要が出てきました。そこで、Visual Studio Code（以下 VSCode）の拡張機能である、 Swagger Viewer を導入しました。

Swagger Viewer 導入方法

VSCode の拡張機能から Swagger Viewer を探してインストール。

YAMLファイルを選択中に、Shift + Option + P を押すとビュワーが開きます。

使ってみる

OpenAPIの定義に従っての infoやserversを書きます。

openapi: 3.0.0
info:
  title: Test API
  version: "1.0"
  description: Testのapi郡
  contact:
    name: Me
servers:
  - url: "https://127.0.0.1:4000/api"

ビュワーの方では、タイトルや詳細説明が表示されます。

続いて、 get メソッドを書いてみます。

tags:
  - name: user
    description: ユーザー個人の情報
paths:
  "/email/{user_id}":
    parameters:
      - schema:
          type: string
        name: user_id
        in: path
        required: true
    get:
      summary: email取得API
      tags:
        - user
      operationId: get-email-user_id
      responses:
        "200":
          description: OK
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Email"
              examples:
                example-1:
                  value:
                    email: sample-fetched@example.com
      description: |-
        ユーザーのemailを取得する

ビュワーの方はこのような形で、operationId やパラメーターが確認できます。

レスポンスの確認もできます。

スキーマーのパートもビュワーで確認できます。

components:
  schemas:
    Email:
      title: Email
      type: object
      additionalProperties: false
      properties:
        email:
          type: string