OpenAPI (Swagger)

編集ツール

editor.swagger.io

サンプル

openapi: 3.0.0

info:
  title: Sample API
  description: A short description of API.
  version: 1.0.0

paths:
  # paths オブジェクト
  /users:
    # path item オブジェクト
    get: # GET
      # Operationオブジェクト
      tags:
        - users
      summary: Get all users.
      description: Returns an array of User model
      parameters: []
      responses: # レスポンス定義
        '200': # HTTP status
          description: A JSON array of User model
          content:
            application/json: # レスポンスの形式指定
              schema: 
                type: array
                items:
                  $ref: '#/components/schemas/User' # 参照するモデル
                example: # サンプルデータ
                  - uid: 1
                    name: John Doe
                  - uid: 2
                    name: Jane Doe
    post: # POST
      tags: 
        - users
      summary: Create a new User
      description: Create a new User
      parameters: []
      requestBody: # リクエストボディ
        description: user to create
        content:
          application/json:
            schema: # POSTするオブジェクト
              $ref: '#/components/schemas/User'
            example:
              uid: 3
              name: Richard Roe
      responses:
        '201':
          description: CREATED
  /users/{userId}:
    get:
      tags:
        - users
      summary: Get user by ID.
      description: Returns a single User model
      parameters: # リクエストパラメータ
        - name: userId
          in: path # パラメータをパス内に含める
          description: user id
          required: true
          schema:
            type: integer
      responses:
        '200':
          description: A single User model
          content:
            application/json:
              schema: 
                type: object
                items:
                  $ref: '#/components/schemas/User'
                example:
                  uid: 1
                  name: John Doe
                  
  /products:
    # path item オブジェクト
    get: # GET
      # Operationオブジェクト
      tags:
        - products
      summary: Get all products.
      description: Returns an array of Products model
      parameters: []
      responses: # レスポンス定義
        '200': # HTTP status
          description: A JSON array of Product model
          content:
            application/json: # レスポンスの形式指定
              schema: 
                type: array
                items:
                  $ref: '#/components/schemas/Product' # 参照するモデル
                example: # サンプルデータ
                  - pid: 1
                    name: tablet
                  - pid: 2
                    name: iphone
    post: # POST
      tags: 
        - products
      summary: Create a new User
      description: Create a new User
      parameters: []
      requestBody: # リクエストボディ
        description: user to create
        content:
          application/json:
            schema: # POSTするオブジェクト
              $ref: '#/components/schemas/Product'
            example:
              pid: 3
              name: disc
      responses:
        '201':
          description: CREATED

                  
                  
components:
  schemas: # スキーマオブジェクトの定義
    User: # モデル名
      type: object # 型
      required: # 必須フィールド
        - uid
      properties:
        uid: # プロパティ名
          type: integer # 型 
          format: int64 # フォーマット(int32, int64等)
        name:
          type: string
    Product:
      type: object
      required:
        - pid
        - price
      properties:
        pid:
          type: integer
          format: int64
          example: 1
        name:
          type: string
          example: Laptop
        price:
          type: integer
          example: 1200

参考

qiita.com

qiita.com