Zenn
Open12

Web API

Swagger
OpenAPI
hbsnowhbsnow

ルートのOpenAPIドキュメントにはopenapi.jsonまたはopenapi.yamlの名前がつけられることがおすすめされています。

hbsnowhbsnow

OpenAPI Object

OpenAPIドキュメントのルートドキュメントオブジェクト

  • openapi REQUIRED
    • OpenAPIのバージョン、最新は 3.0.3
  • info REQUIRED
    • APIに関するメタデータ
  • servers
    • サーバーへの接続情報。デフォルト値はURL値が/のサーバーオブジェクト
  • paths REQUIRED
    • APIの利用可能なパスとoperations
  • components
    • 仕様書の様々なスキーマを保持するためのelement
  • security
    • API全体でどのセキュリティメカニズムを使用できるか
  • tags
    • 仕様書で使用されているタグのリストに、追加のメタデータを加えたもの
  • externalDocs
    • 外部ドキュメント
hbsnowhbsnow

server

servers:
  - url: http://localhost:8010/v1
    description: Localhost server
  - url: http://dev.excample.com/v1
    description: Development server
  - url: http://stg.excample.com/v1
    description: Staging server
  - url: http://api.excample.com/v1
    description: Production server
hbsnowhbsnow

path

Operation Object

  • operationId - OpenAPI Generator でメソッド名などに使用される。すべての Operation で一意でなければならない

Schema Object

https://swagger.io/docs/specification/data-models/data-types/

  • integer - 整数
  • number - 小数
  • string
  • boolean
  • array
  • object

formatはオープンな値なので、OpenAPI仕様で定義されていないフォーマットであっても使用することができます。

paths:
  /cloths:
    get:
      tags:
        - cloth
      summary: 生地一覧
      description: 所持している生地の一覧
      operationid: getCloths
      responses:
        "200":
          description: 生地の一覧
          content:
            application/json:
              schema:
                type: array
                items:
                  type: object
                  description: 生地データ
                  required:
                    - clothId
                    - photo
                    - price
                    - createdAt
                    - updatedAt
                  properties:
                    clothId:
                      type: string
                      description: 生地ID
                      example: cloth0001
                    photo:
                      type: string
                      format: uri
                      description: 生地の写真の URL
                      example: https://example.com/cloth0001.jpg
                    price:
                      type: integer
                      description: 10cm単位の価格
                      example: 300
                    createdAt:
                      type: string
                      format: date-time
                      description: 作成日
                    updatedAt:
                      type: string
                      format: date-time
                      description: 更新日