Swagger(OpenAPI)でエラーメッセージを返すスキーマを定義する時はenumにしておくと便利

Web APIを実装する時にクライアントのBadRequestエラー(400)の時に、
重複のエラーメッセージを返したい場合、最初は以下のようなスキーマを定義していた。

DuplicatedUserId:
  description: ID重複
  type: object
  required:
    - message
  properties:
    message:
      type: string
      example: id duplicated

ただこれだとBadRequestの理由が増えた時にその分スキーマが増えてしまうのと、
理由をチェックするためにプログラム側で文字列比較のコードを書かないといけなくなってしまう。

そのため今では以下のようにenumで定義するようにしている。

BadRequestUser:
  description: Userのリクエストエラー
  type: object
  required:
    - message
  properties:
    message:
      description: エラーメッセージ
      type: string
      enum:
        - duplicatedId

こうしておくとエラーの理由が増えた時に対応しやすくなるのと、動作確認も自動で行うことができる。

例えばRailsでAPIを実装している場合は、
commiteee-railsでAPIのレスポンスがSwaggerのスキーマと一致しているかをチェックできる。

もしBadRequestUserのエラーメッセージがenumに定義されていない内容だと、
テストの時点で自動でエラー判定をしてくれる。

動作確認が漏れずにすみ、とても便利！