Swagger Viewer で OpenAPI定義を書く

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

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

関連

OpenAPI と Stoplight Studio については以下の記事がおすすめです!

OpenAPI の定義を Stoplight Studio で書く

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

おわりに

使いやすいと感じたところ

  • 定義ファイルの更新でビュワーもリアルタイムで更新される
  • ページのタブごとにAPIがまとめられる
  • $ref で複数ページをまたいでいても問題なく表示される

ちょっと使いにくいと感じたところ

  • 定義ファイルとビュワーの位置が連動してない
  • ビュワー内は API や Schema の検索ができない

OpenAPIの定義ファイルが快適に記述できるテクニックが見つかれば、また共有いたします!

Gaji-Laboでは、React経験が豊富なフロントエンドエンジニアを募集しています

弊社ではReactの知見で事業作りに貢献したいフロントエンドエンジニアを募集しています。大きな制作会社や事業会社とはひと味もふた味も違うGaji-Laboを味わいに来ませんか?

もちろん、一緒にお仕事をしてくださるパートナーさんも随時募集中です。まずはお気軽に声をかけてください。お仕事お問い合わせや採用への応募、共に大歓迎です!

求人応募してみる!

投稿者 Chaki Hironori

webライターもやってるフロントエンドエンジニアです。Reactは自信があります。またデザイン畑の出身で、気持ちのいいアニメーションやインタラクティブな表現は丁寧に手掛けます。好きなものは中南米の遺跡で、スペイン語が少しできます。