Swaggerでエラー一覧書くのにだいぶ悩んでいます

Swaggerでエラー一覧を書きたいです。

調べてみると以下の記事が。

qiita.com

参照されているGitHubを見てみると、このように書かれていました。 Swagger 3.0 Example · GitHub

該当部分L127-L149を引用します。

Error:
  description: |
    <table>
      <tr>
        <th>Code</th>
        <th>Description</th>
      </tr>
      <tr>
        <td>illegal_input</td>
        <td>The input is invalid.</td>
      </tr>
      <tr>
        <td>not_found</td>
        <td>The resource is not found.</td>
      </tr>
    </table>
  required:
    - code
    - message
  properties:
    code:
      type: string
      example: illegal_input

なるほど。。。テーブルで定義するんですね。どうやらmarkdown形式でも書けるみたい。

www.baeldung.com

引用します

      description: |

        **The below table defines the HTTP Status codes that this API may return**

        | Status Code      | Description | Reason                             |
        | ---------------- | ------------| -----------------------------------|
        | 201              | CREATED     | If a pet is created successfuly.   |
        | 400              | BAD REQUEST | If the request is not valid.       |
        | 401              | UNAUTHORIZED| If the credentials are invalid.    |

はい。なんかこれ書くのマジで辛そう。

安直にenumで定義してしまえばいいかもしれませんが、API利用側のチームの方々にとってそれがわかりやすいかと言われると微妙ですね。エンジニア以外の人も読む可能性あるし。

大正義エクセルで書いてもいいけどメンテナンスが大変になりますね。

ということで今日の悩みでした。誰かに相談しよう。