プリセットAPIにHTTP 422のAPIドキュメントを追加したい

[aoirint]

内容

#711 (comment) で挙がった内容をふまえて、Issue化します。

プリセットAPIは、さまざまな要因で実行に失敗した場合に、HTTP 422を返します。
APIを実行すると原因が返るようになっていますが、APIドキュメントには含まれていません。

プリセット関連のAPIエンドポイントで、HTTP 422が返る状況について、APIドキュメントを追加したいです。

• 例 POST /validate_kana: https://voicevox.github.io/voicevox_engine/api/#tag/%E3%81%9D%E3%81%AE%E4%BB%96/operation/validate_kana_validate_kana_post
  • プリセットAPIの場合、基本的にサーバ側のエラーなので、ここまで詳細でなくてよさそう？（descriptionだけ）

Pros 良くなる点

• APIを実行せずに挙動がわかるようになる

Cons 悪くなる点

実現方法

こんな感じでdescriptionを追加できるはずです（"model"はレスポンスをカスタムしない場合は不要）。

voicevox_engine/run.py

Lines 1077 to 1082 in b64db22

	responses={
	400: {
	"description": "テキストが不正です",
	"model": ParseKanaBadRequest,
	}
	},

• FastAPIのドキュメント: https://fastapi.tiangolo.com/advanced/additional-responses/#combining-information

VOICEVOXのバージョン

0.15 開発版

その他

[Hiroshiba]

良いと思います！！ぜひ･･･！

[tarepan]

#1162 にて 422 / 500 の整理をおこないました。
その結果、10パターン近い異常系があることが明確化されました。
この全てを FastAPI path operation に記述することは一応可能です。
ただ全エラー挙動を docs で知りたいという需要はかなり薄そうに感じます。
一方で、注釈が必要な特定エラーに関しては妥当かと思います。

@Hiroshiba
本 issue の必要性は現在でも変わっていない感じでしょうか？

[Hiroshiba]

少なくともプリセットAPIだけではなく、全APIに対して言えそうだなと思いました。

一般論として、エラーがどういうときに起こるのかとか、直感に反するエラー挙動をしたりする場合のドキュメントはあったほうが有用だとは思います。

うーん、ネガティブケースのドキュメントの優先度をどうするかの哲学を持っておらず、判断を悩んでいます。
これが割としっかりしないといけないマイクロサービスの納品とかであれば絶対書くべきなのですが･･･。

少なくとも致命性が高いものや、よく起こるけど原因がわかりづらいエラーは案内してあげても良いかもと思いました。
そういう意味では少なくともプリセットAPIのエラードキュメントはそこまで優先度を上げなくても良いかもです。

[sabonerune]

あとはエラーが起きた時それに対処可能である場合とかでしょうか？

[Hiroshiba]

あとはエラーが起きた時それに対処可能である場合とかでしょうか？

有用ですが、書くならドキュメントじゃなくエラーメッセージ側でも良いかもと思いました！
といってもエラーから離れすぎると違う案内をしてしまうかもなので、例えばファイルがなかった場合にファイルが見つかりませんでした。{path}にファイルがあるか確認してください。みたいな感じかもですが。

うーん！　あっても良いし、どちらかというとあったほうが良いけど、まあ最悪なくても良いかな！！
より優先度の高い項目がありそう！！　v2 APIの設計とか！！

[sabonerune]

あ、対処可能であるというのはプログラムがAPIを叩いてエンジンがエラーを返したときにプログラム側でエラー内容を読み取って処理が変更可能かどうかということですね。

ただよく考えるとVOICEVOXにそのようなタイプのAPIはない？

[Hiroshiba]

なるほどです！！エラーコードを返す的な感じかな。

対処を変えないといけないレベルのは、大体はステータスコードレベルから変わってそうな気がしました！
入力がおかしいかサーバー側がおかしいかとか、corsとか、get/post違いとか。

あ、sing系APiはもう少しエラー細分化してあげても良いかも。

あとは「どのパラメーターがおかしい」とかはエラーコード分けて返してあげるとしっかりしてるエディタはしっかり活用してくれるかもですね。

まあでも…なんかこう、別に良いかなみたいな気持ちになっちゃいますね…なんでだろう…

[github-actions]

本 Issue は直近 180 日間で活動がありません。今後の方針について VOICEVOX チームによる再検討がおこなわれる予定です。