この記事は公開されてから1年以上経過しています。情報が古い可能性がありますので、ご注意ください。
こんにちは、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)とでスキーマ仕様が似ているようで異なっており、覚えるのが大変なので、バリデーションやプレビューが行えるのはとても助かりますね。
参考
以上