このエントリーをはてなブックマークに追加

swagger

RESTful APIを構築するためのオープンソースのフレームワーク
Swagger Spec を書いておけば自動的にドキュメント生成することができる。
2.0系と3.0系で記載方法が変わっている。

Swagger Spec

REST APIに対して Swagger の仕様に準じたドキュメント

Swagger Editer

Swagger ファイルの生成や編集を行うためのツール

Swagger UI

Swagger-Specを読み込んで、HTML形式でドキュメントを生成するためのツール

Swagger Codegen

Swagger specよりAPIのスタブを作成するためのツール

3.0のサンプルイメージ

  • exsample_v3.0.0.yml

    openapi: '3.0.0'
    info:
      title: 'example'
      version: '1.0'
    servers:
      - url: https://localhost:8080
        description: 開発テスト環境
      - url: https://api.server.test/v1
        description: 結合試験環境
    paths:
      /call-example/{id}:
        description: 参照のサンプル
        $ref: ./call-exsample.yml
      /call-update:
        description: 更新のサンプル
        $ref: ./call-update.yml
    
  • call-exsample.yml

    get:
      tags:
        - 参照のサンプル
      description: 基本情報
      summary: Get a user by ID
      parameters:
        - in: path
          name: id
          schema:
            type: string
          required: true
          description: Numeric ID of the user to get
      responses:
        '200':
          description: 成功時のレスポンス
          content:
            application/json:
              schema:
                type: object
                properties:
                  result:
                    type: string
                    example: "success"
        '400':
          $ref: ./err.yml
    
  • call-update.yml

    # 更新用リクエスト
    post:
      tags:
        - 更新のサンプル
      description: 更新のサンプル
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                id:
                  description: |
                    id 数値10桁
                  type: string
                  example: "00000000000"
                  format: "9999999999"
                mailAddress:
                  type: string
      responses:
        '200':
          description: 成功時のレスポンス
          content:
            application/json:
              schema:
                type: object
                properties:
                  result:
                    type: string
                    example: "success"
        '400':
          $ref: ./err.yml
    
  • err.yml

    content:
      application/json:
        schema:
          type: object
          properties:
            error:
              type: string
              example: invalid_request
            error_description:
              type: string
              example: アクセストークンが指定されていません
    

便利なツール

vccodeの拡張機能を利用することで「Swagger Editer」を利用しなくても作成することができる

  • OpenAPI (Swagger) Editor
  • Swagger Viewer

参考サイト