OpenAPI 入門 Part4 | 番外編

今回はOpenAPI入門の番外編ということで、書かなくても動くが、書いてあった方が丁寧というものを紹介していきます.

description

名前の通り説明を追加するところです.
このプロパティは色々なところで書くことができます. 具体的には

• APIの説明
• 各エンドポイントの説明
• レスポンスステータスごとの説明
  があります.

openapi.yaml

openapi: 3.1.0
info:
  title: MyAPI
  version: 0.0.1
  description: This is X clone API #APIの説明
paths:
  /posts:
    get:
      description: Get post list #各エンドポイントの説明
      responses:
        '200':
          description: post 200 response #レスポンスステータスごとの説明
          content:
            application/json:
              schema:
                $ref: "./schema.yml#/Posts"

これらは Swagger Previewで表示されるので書いておくと親切でしょう.

example

exampleはSwaggerUIなどで見たときに、レスポンスのサンプルとして表示される値を指定できます.

schema.yaml

Posts:
  type: array
  items:
    $ref: "#/Post"
Post:
  type: object
  properties:
    text:
      type: string
      example: おはよう！
    imgSrc:
      type: string
      example: https://example.com/image1.png

swaggerUI example

デフォルトの値が入っているよりもイメージがしやすいので、ぜひ設定しておきましょう.