Zenn
Closed4

Swagger導入メモ

VS Code
API
YAML
Swagger
nekonikinekoniki

概要

REST API構築するためのインターフェース構築言語。

サンプル

http://hogehogeを基底とし、/helloと/nameというエンドポイントを持つREST APIの定義例

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

# 基本情報
info:
  version: 1.0.0
  title: Swagger-Test-API
  description: |
    #### ここにはAPIの説明が入ります。
# リクエスト方式
shemas:
  - http
  - https
# ホスト
host: localhost:8085
# 基底パス
basePath: /swagger-sample/sample
# タグ定義
tags:
  - name: "test"
    description: this is tag description
    externalDocs:
      description: "Find out more"
      url: "http://hogehoge"
# エンドポイント
paths:
  /hello:
    get:
      tags:
        - test
      response:
        200:
          description: Hello World
      parameters:
        - name: id
          in: hoge
          required: true
          type: number
  /name:
    post:
      tags:
        - test
      produces:
        - application/x-www-form-urlencoded
      consumes:
        - application/text/plain
      response:
        200:
          description: HogeHoge
      parameters:
        - name: name
          in: formData
          description: name
          type: string
          required: true
nekonikinekoniki

VSCode拡張

Swagger-Viewer1

使い方

対象となるyamlをVScodeで開いている状態でShift+Alt+p

Swagger-Viewer2

nekonikinekoniki

Zenn記事投稿用にある程度しっかりとまとめた版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

  • 出力サンプル1

  • 出力サンプル2

このスクラップは2020/12/03にクローズされました