Zenn
🦢

VSCodeでSwaggerViewerを導入する

2020/12/03に公開
VS Code
API
tool
Swagger
拡張機能
tech

はじめに

最近Swaggerを触る機会がありました。
YamlやJsonで定められたフォーマットで記載することで、REST APIの仕様やドキュメントの構築を簡単に行えるので、次にAPI設計を行う場合は本格的に使いたいなと思います。

そんなSwaggerですが通常はSwagger Editorを使って編集します。
しかしながらローカルで作業したくなる場合もあるかと思い、VSCodeでできないか調べたところまさに求めていた拡張機能があったので紹介したいと思います。

そもそもSwaggerとは？

以下、翻訳して要点をまとめたものです。

  • SwaggerはREST APIを記述するためのインターフェース言語
  • JSNOやYAMLで記載する
  • サードパーティ製ツールを仕様することで高品質のドキュメントやスタブを自動生成できる

REST APIの開発元はSwaggerで記述することで、サードパティ製の様々なサポートツールを利用することができます。

VSCode用の拡張機能「Swagger Viewer」

今回使用するのはSwagger Viewerという拡張機能です。

Swagger Viewr

これを使うことで、VSCodeでSwaggerを編集しながらプレビューを動的に生成することができます。

インストール

GUIもしくは下記コマンドでインストールできます。

code --install-extension arjun.swagger-viewer

サンプルコード

以下のようなsample.yamlを作成しましょう。
サンプルとして、ZennのREST APIを想定しています。

sample.yaml
# swaggerバージョン宣言
swagger: "2.0"

# 基本情報
info:
  # バージョン表記
  version: 1.0.0
  # タイトル
  title: Swagger-Test-API
  # 説明
  description: |
    - Zenn投稿用にSwaggerサンプルを作りました。
    - 各種エンドポイントは適当です
# リクエスト方式
schemes:
  - http
  - https
# ホスト
host: localhost:8080
# 基底パス
basePath: /swagger-sample/zenn/api/
# タグ定義
tags:
  - name: "Article"
    description: 記事に関するエンドポイント
    externalDocs:
      description: "AAAAAAAAAA"
      url: "http://hogehoge"
  - name: "Book"
    description: 書籍に関するエンドポイント
    externalDocs:
      description: "BBBBBBBBBB"
      url: "http://fugafuga"
# エンドポイント
paths:
  /articles:
    get:
      summary:
        記事一覧を取得
      tags:
        - Article
      responses:
        200:
          description: Hello World
          schema:
            type: array
            example: [
              {
                id: ef304778ada8a6, 
                title: ReactNative@v0.63で追加されたPressableが地味にすごい,
                link: https://zenn.dev/nekoniki/articles/ef304778ada8a6
              }
            ]
  /articles/{id}:
    get:
      summary: 
        指定した記事の詳細を取得
      tags:
        - Article
      responses:
        200:
          description: OK
          schema:
            type: object
            properties:
              id:
                type: string
                example: ef304778ada8a6
              author:
                type: string
                example: ネコニキ
              title:
                type: string
                example: ReactNative@v0.63で追加されたPressableが地味にすごい
              link:
                type: string
                example: https://zenn.dev/nekoniki/articles/ef304778ada8a6
      parameters:
        - name: id
          in: header
          type: string
          required: true
  /books/{id}:
    delete:
      summary:
        指定した書籍の削除
      tags:
        - Book
      produces:
        - application/x-www-form-urlencoded
      consumes:
        - application/text/plain
      responses:
        200:
          description: 削除完了時のレスポンス
      parameters:
        - name: id
          in: header
          type: string
          required: true

Swaggerのフォーマットに慣れない方のために簡単に内容を説明すると、以下のような定義を行っています。

  1. /swagger-sample/zenn/api/を基底とするSwagger-Test-APIというAPIを定義
  2. タグ(APIの区分と置き換えても構いません)としてArticleとBookを定義
  3. Articleに属するエンドポイントとして/articlesと/articles/{id}を定義
  4. Bookに属するエンドポイントとして/books/{id}を定義

プレビュー

続いてSwagger Viewerを使ってプレビューしてみましょう。
sample.yamlを開いた状態で以下を行うことでプレビューができます。

  1. Shift+command+pでコマンドパレットを開く(WindowsはShift+Alt+p)
  2. コマンドパレットからPreview Swaggerを選択

prev1

先ほど定義した内容が整形されて参照できるようになりました。
試しに/articlesのエンドポイントを開いてみると、定義した内容の詳細が確認できることがわかります。

prev2

まとめ

今回はSwagger Viewerを使ってVSCodeでSwaggerのプレビューを参照する方法についてご紹介しました。
この段階ではあくまで「プレビュー」で、実際には今回作成したsample.yamlを使ってドキュメントやスタブを作っていくことになります。

その場合にはまた別のSwaggerをサポートしたツールを使っていくことになります。
こちらはまた別記事で紹介したいと思います。

Discussion