Swaggerでエラー一覧を書きたいです。
調べてみると以下の記事が。
参照されている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形式でも書けるみたい。
引用します
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利用側のチームの方々にとってそれがわかりやすいかと言われると微妙ですね。エンジニア以外の人も読む可能性あるし。
大正義エクセルで書いてもいいけどメンテナンスが大変になりますね。
ということで今日の悩みでした。誰かに相談しよう。