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

#Swagger

#VSCode（Visual Studio Code）

若槻龍太

2022.05.12

この記事は公開されてから1年以上経過しています。情報が古い可能性がありますので、ご注意ください。

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

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

OpenAPI Specification - Version 3.0.3 | Swagger

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

OASドキュメント

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

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ドキュメントの編集中にバリデーションを行うことができます。

YAML - Visual Studio Marketplace

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

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

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