Swaggerのコンポーネントを正しく使ってきれいに書く

apiの仕様書として、swaggerを使っていますが行数が増えてきたので、コンポーネントを使って短く書く方法を調べました。

Swaggerのコンポーネントとは

Often, multiple API operations have some common parameters or return the same response structure. To avoid code duplication, you can place the common definitions in the global components section and reference them using $ref.

同じ記述を減らすためにswaggerがapiに必要なものを提供してくれています。

components:
  # Reusable schemas (data models)
  schemas:
    ...
  # Reusable path, query, header and cookie parameters
  parameters:
    ...
  # Security scheme definitions (see Authentication)
  securitySchemes:
    ...
  # Reusable request bodies
  requestBodies:
    ...
  # Reusable responses, such as 401 Unauthorized or 400 Bad Request
  responses:
    ...
  # Reusable response headers
  headers:
    ...
  # Reusable examples
  examples:
    ...
  # Reusable links
  links:
    ...
  # Reusable callbacks
  callbacks:
    ...

コンポーネントの使い方サンプル

実際にどうやって使うか書いてみました。

parameters

paths:
  /article/{articleId}:
    patch:
      summary: edit article
      parameters:
        - $ref: '#/components/parameters/userId'
        - $ref: '#/components/parameters/articleId'

components:
  parameters:
    userId:
      name: X-User-ID
      in: header
      description: user id
      required: true
      schema:
        type: integer
    articleId:
      name: articleId
      in: path
      description: article id
      required: true
      schema:
        type: integer

requestBodies

作成や更新で必要になるrequest bodyもコンポーネントを組み合わせることで短く出来ます。
https://swagger.io/docs/specification/describing-request-body/

paths:
  /article/{articleId}:
    patch:
      requestBody:
        $ref: '#/components/schemas/article'
components:
  requestBodies:
    article:
      description: A JSON object containing article information
      required: true
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/article' # contentもコンポーネントを使うことで簡潔になる
  schemas:
    article:
      type: object
      required:
        - title
        - sentence
      properties:
        title:
          type: string
        sentence:
          type: string

responses

エラー処理などの共通のレスポンスに対して短く出来ます。
https://swagger.io/docs/specification/describing-responses/

paths:
  /article/{articleId}:
    patch:
      responses:
        '200':
          $ref: '#/components/responses/success'
        '404':
          $ref: '#/components/responses/notFound'
components:
  responses:
    success:
      description: Success
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Success'
    notFound:
      description: Not found
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/notFoundError'

まとめ

もともとコンポーネントをschemasくらいしか使っていなかったために共通の処理をまとめたところ、2000行以上のswaggerファイルで400行程短く出来ました。
まだリファクタの途中なので、今後さらに共通化を進めて綺麗にできそうです。
swaggerを書こうとしている方の参考になれば嬉しいです。