swaggerをvscodeで書いてみた

swagger Viewer

RESTful APIの使用を記述するフォーマットにOpenAPIという規格があり、
OpenAPIを使用するツールにSwaggerがあります。

VSCodeでAPI仕様書を書きたい。
そんなときはSwagger Viewerを使いましょう。
拡張機能をインストールします。

swaggerの書き方

swagger: "2.0"

info:
  version: "1.0.0"
  title: users
paths:
  /users:
    get:
      description: ユーザー情報を取得する
      parameters:
        - name: name
          in: query
          description: user name
          type: string
      responses:
        200:
          description: Successful response
          schema:
            title: ArrayOfUsers
            type: array
            items:
              title: User
              type: object
              properties:
                name:
                  type: string

info

ドキュメントのバージョン、タイトルを記述します。

paths

pathsにエンドポイントを記述します。
リソースIDを利用する場合は以下のように記述します。

paths:
  /user/{id}

HTTPメソッドを指定し、descriptionに説明を記述します。
parametersにHTTPパラメータを記述し、responsesにレスポンス情報を記述します。

paths:
  /users:
    get:
      description:
      parameters:
      responses:

parameters

名前	説明
name	パラメータ名
in	query: /users?id=1　 path: /users/{id}
description	パラメータの説明
required	必須か否か
type	型

responses

名前	説明
description	レスポンスの説明
schema	レスポンスの値
type	型
items	中身
properties	プロパティ情報