VSCodeでOpenAPI Specificationドキュメントを編集する際に便利なプラグインたち

2022.05.12

こんにちは、CX事業本部 IoT事業部の若槻です。

REST APIを実装する際に、API仕様書としてOpenAPI Specification(OAS、Swagger)準拠のドキュメントをよく作成するのですが、OASドキュメントはとても記述量が多くなることがあり、何の記述支援もなく編集するとなると結構たいへんです。

そこで今回は、VSCodeでOASドキュメントを編集する際に使ってみたら便利だったプラグインを紹介します。

OASドキュメント

参考として、次のようなOASドキュメント(Yamlファイル)で試してみます。

specfile.yml

openapi: 3.0.3
info: 
  title: Hoge REST API
  version: 0.0.1
tags:
  - name: user
    description: ユーザー
servers: 
  - url: https://xxxxxxxxxxx.execute-api.ap-northeast-1.amazonaws.com/v1
    description: 開発環境
security:
  - Bearer: []
paths:
  /users:
    get:
      tags: 
        - user
      summary: ユーザーリスト取得
      responses:
        200:
          description: 成功
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/UserItem'
        401: 
          description: 認証エラー
        403: 
          description: 認可エラー
        500:
          description: サーバーエラー
  /users/{userId}:
    get:
      tags: 
        - user
      summary: ユーザー取得
      parameters:
        - name: userId
          in: path
          schema:
            type: string
          required: true
      responses:
        200:
          description: 成功
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UserItem'
        401: 
          description: 認証エラー
        403: 
          description: 認可エラー
        404: 
          description: リソース未検出エラー
        500:
          description: サーバーエラー
components:
  schemas:
    UserItem:
      type: object
      properties:
        userId:
          type: string
          description: ユーザーID
          example: 4a5c678e-22b3-4132-946d-74c9cc04bbe0
        userName:
          type: string
          description: ユーザー名
          example: 二次元社員めそ子
  securitySchemes:
    Bearer:
      type: http
      scheme: bearer
      description: Access token for API

プラグイン

ここでは次の2つのプラグインを紹介します。

  • YAML
  • Swagger Viewer

YAML

YAMLを使うと、OASドキュメントの編集中にバリデーションを行うことができます。

開いたOASドキュメントのファイルの上部にopenapi.jsonと表示されていれば、YAMLによるバリデーション対象として認識されています。

OASのスキーマ仕様に違反した記述があるとバリデーションエラーとなります。

ちなみにYAMLはJSON Schema(JsonおよびYamlの各種ドキュメントの規格を行うオープンソースプロジェクト)をサポートしているため、OAS以外にも様々なドキュメントに対応しているので、OASドキュメントをあまり編集しない場合でも導入しておいて損は無いと思います。対応しているドキュメント一覧は下記で確認可能です。

Swagger Viewer

Swagger Viewerを使うと、OASドキュメントのSwagger UIをVS Code上でプレビューすることができます。

プラグインをインストールしたら、OASドキュメントのファイルにフォーカスした状態でShift + option + pキーによりプレビューを開けるようになります。

画面左側のファイルのプレビューを右側に表示している様子です。ファイルの編集はリアルタイムでプレビューへ反映されます。

もちろん各リソースは展開して詳細を見ることもできます。

[Try it out]より各リソース/メソッドへのリクエストも行うことができます。

認証が必要なAPIは[Authorize]よりリクエストに使用する認証情報を指定できます。ドキュメントのsecuritySchemesで指定した認証方式をちゃんと求められます。(画像はBearerの場合)

Swagger EditorというファイルをインポートしたらSwagger UIを表示できる公式ツールもあるにはあるのですが、そちらと比べて編集したそばからプレビューできるというのは便利過ぎますね。

おわりに

VSCodeでOpenAPI Specificationドキュメントを編集する際に便利なプラグインの紹介でした。

OASドキュメントはOpenAPI Specification(3.0.X)と、その前身であるSwagger(1.Xおよび2.0)とでスキーマ仕様が似ているようで異なっており、覚えるのが大変なので、バリデーションやプレビューが行えるのはとても助かりますね。

参考

以上