APIRoute の tag を英語にし、description を日本語にする

[raa0121]

内容

APIRoute の tag を英語にすると、openapi-codegen する際に、api_[tag名].ts が生成される。
そのまま、英語にした場合、API Doc で英語表示になるため、description を指定する。

Pros 良くなる点

• api_[tag名].ts として生成されると、tag名のクラスも生成され、利用する側もわかりやすくなる。

Cons 悪くなる点

• API Doc の見た目が変化する
  Before:
  
  After:
  

実現方法

以下のような diff を用意する

diff --git a/voicevox_engine/app/application.py b/voicevox_engine/app/application.py
index 14fc89d..82e378f 100644
--- a/voicevox_engine/app/application.py
+++ b/voicevox_engine/app/application.py
@@ -34,6 +34,37 @@ from voicevox_engine.utility.path_utility import engine_root
 from voicevox_engine.utility.runtime_utility import is_development
 
 
+tags_metadata = [
+    {
+        "name": "create query",
+        "description": "クエリ作成",
+    },
+    {
+        "name": "edit query",
+        "description": "クエリ編集",
+    },
+    {
+        "name": "other",
+        "description": "その他",
+    },
+    {
+        "name": "settings",
+        "description": "設定",
+    },
+    {
+        "name": "synthesis",
+        "description": "音声合成",
+    },
+    {
+        "name": "user dict",
+        "description": "ユーザー辞書",
+    },
+    {
+        "name": "audio library",
+        "description": "音声ライブラリ管理",
+    },
+]
+
 def generate_app(
     tts_engines: TTSEngineManager,
     core_manager: CoreManager,
@@ -61,6 +92,7 @@ def generate_app(
         description=f"{engine_manifest.brand_name} の音声合成エンジンです。",
         version=__version__,
         separate_input_output_schemas=False,  # Pydantic V1 のときのスキーマに合わせるため
+        openapi_tags=tags_metadata,
     )
     app = configure_middlewares(app, cors_policy_mode, allow_origin)
     app = configure_global_exception_handlers(app)
diff --git a/voicevox_engine/app/routers/character.py b/voicevox_engine/app/routers/character.py
index 4ff6077..b0c731a 100644
--- a/voicevox_engine/app/routers/character.py
+++ b/voicevox_engine/app/routers/character.py
@@ -37,7 +37,7 @@ def generate_character_router(
     resource_manager: ResourceManager, metas_store: MetasStore
 ) -> APIRouter:
     """キャラクター情報 API Router を生成する"""
-    router = APIRouter(tags=["その他"])
+    router = APIRouter(tags=["other"])
 
     @router.get("/speakers")
     def speakers(core_version: str | SkipJsonSchema[None] = None) -> list[Speaker]:

VOICEVOXのバージョン

0.22.0

OSの種類/ディストリ/バージョン

• Windows
• macOS
• Linux

その他

[Hiroshiba]

どちらかというとネガティブ寄りの印象でいます･･･！ 🙇

まずOpenAPIはVOICEVOXエディタ開発が楽になるようにという意図で作っているのですが、ファイルが分かれることはmockや抽象化がしづらくなるのでエディタにとってはただ不便になりそうな気がしてます。
ただこれは実際エディタ側でOpenAPI generatorを動かしてみて、それに合わせる場合エディタ側を変更でき、かつメンテもしんどくなければOKかなと。

２つ目がドキュメントの見た目が変わる点で、日本語ドキュメントで謎の英単語が太字で表示されてるのは視認性が悪くなってると感じました。
逆だったら問題ない気がします。実はnameとdescription以外にkeyみたいなのがあったりしないかな･･･。

あとタグ名を変えだけでOpenAPIに依存しているコードが動かなくなるのも、それは嬉しいことなんだろうかと感じました。
これはそもそもgenerator側がタグのnameをファイル名に持ってくる仕様が若干微妙な気がします･･･ 😇

それとファイルが分かれることは、個人的にはそこまで便利なように感じないかもです！
全然関係ないのですが、エディタ側でOpenAPI generatorを使うと、API名がhogeFugaHogeFugaPostみたいに名前が２連続してしまうんですよね。
これは単純にメンテナンス性が下がってるように感じていたので、もしこの名前２連続がなくなるならアリかもと思いました！！

---

OpenAPI自体はそこそこ便利そうなので、もう少し整備しても良いかもと感じています。
ただVOICEVOX的に今のところ優先度がだいぶ低いのですが、積極的にしてくださるならウェルカムです！！

[Hiroshiba]

Discord側で、redocはもっと見た目変わってしまうことがわかったので転載させていただきます！
（@raa0121 さん @takana-v さんありがとうございます！）

[raa0121]

nameとdescription以外にkeyみたいなのがあったりしないかな･･･。

https://swagger.io/docs/specification/v3_0/grouping-operations-with-tags/
ドキュメント的には、key は存在してないですね…

エディタ側でOpenAPI generatorを使うと、API名がhogeFugaHogeFugaPostみたいに名前が２連続してしまうんですよね。
これは単純にメンテナンス性が下がってるように感じていたので、もしこの名前２連続がなくなるならアリかもと思いました！！

operationId というのを指定すると、生成される関数名を指定できます。
一括で、アノテーションされてる関数名にするための関数が公式で案内されてました。
こちらは、表題とは別で、取り込むと良いと思います。
https://fastapi.tiangolo.com/ja/advanced/path-operation-advanced-configuration/#path-operation-operationid

def use_route_names_as_operation_ids(app: FastAPI) -> None:
    """
    Simplify operation IDs so that generated API clients have simpler function
    names.

    Should be called only after all routes have been added.
    """
    for route in app.routes:
        if isinstance(route, APIRoute):
            route.operation_id = route.name  # in this case, 'read_items'

を voicevox_engine/application.py 定義して、genarate_app の最後に呼び出した状態で生成された openapi.json を用いて、typescript-fetch のライブラリを生成すると、以下のような関数ができました。
https://github.com/VOICEVOX/voicevox/blob/main/src/openapi/apis/DefaultApi.ts#L1200-L1203 に相当するものです。

    /**
     * 音声合成用のクエリの初期値を得ます。ここで得られたクエリはそのまま音声合成に利用できます。各値の意味は`Schemas`を参照してください。
     * 音声合成用のクエリを作成する
     */
    async audioQuery(requestParameters: AudioQueryRequest, initOverrides?: RequestInit | runtime.InitOverrideFunction): Promise<AudioQuery> {
        const response = await this.audioQueryRaw(requestParameters, initOverrides);
        return await response.value();
    }

[Hiroshiba]

エディタ側でOpenAPI generatorを使うと、API名がhogeFugaHogeFugaPostみたいに名前が２連続してしまうんですよね。
これは単純にメンテナンス性が下がってるように感じていたので、もしこの名前２連続がなくなるならアリかもと思いました！！

operationId というのを指定すると、生成される関数名を指定できます。
一括で、アノテーションされてる関数名にするための関数が公式で案内されてました。

おっとなるほどです！
これ原因はジェネレーター側だと思ってたんですけど、FastAPI側だったとは。。。

ありがとうございます、ただこれも適当に変更として取り込むとOpenAPIを使っている人たちに不便だと思うので、慎重に扱った方が良さそうな気がしますね！
とりあえずissue化してみたいと思います！

[Hiroshiba]

こちらですが、ドキュメントの見た目がかなり変わってしまう点（特にredocの左のメニュー欄が日本語でなくなってしまう点）が課題となって実現が難しいのかなと感じています！

おそらくOpenAPIの機能だけでは内部パラメータ(tag)とユーザー向けの説明文を分けるのは無理なんだろうなーと。
一番良い解決策はi18nだと感じますが、だいぶ遠そうな予感がしています。

良いアイデアや、i18n化まで含めた解決にチャレンジしてくださる方をお待ちする形かなと思いますが、どうでしょうか！
（もちろんチャレンジしてくださるのでも･･･！）