ENH: OpenAPIのドキュメントを改良 (#1438)

* ENH: OpenAPIのドキュメントを改良

* FIX: 改行を削除

voicevox_engine/app/routers/engine_info.py

@@ -18,9 +18,9 @@ class SupportedDevicesInfo(BaseModel):
     対応しているデバイスの情報
     """
 
-    cpu: bool = Field(title="CPUに対応しているか")
-    cuda: bool = Field(title="CUDA(Nvidia GPU)に対応しているか")
-    dml: bool = Field(title="DirectML(Nvidia GPU/Radeon GPU等)に対応しているか")
+    cpu: bool = Field(description="CPUに対応しているか")
+    cuda: bool = Field(description="CUDA(Nvidia GPU)に対応しているか")
+    dml: bool = Field(description="DirectML(Nvidia GPU/Radeon GPU等)に対応しているか")
 
     @classmethod
     def generate_from(cls, device_support: DeviceSupport) -> Self:

voicevox_engine/app/routers/tts_pipeline.py

@@ -46,18 +46,18 @@
 
 
 class ParseKanaBadRequest(BaseModel):
-    text: str = Field(title="エラーメッセージ")
+    text: str = Field(description="エラーメッセージ")
     error_name: str = Field(
-        title="エラー名",
-        description="|name|description|\n|---|---|\n"
+        description="エラー名\n\n"
+        "|name|description|\n|---|---|\n"
         + "\n".join(
             [
                 "| {} | {} |".format(err.name, err.value)
                 for err in list(ParseKanaErrorCode)
             ]
         ),
     )
-    error_args: dict[str, str] = Field(title="エラーを起こした箇所")
+    error_args: dict[str, str] = Field(description="エラーを起こした箇所")
 
     def __init__(self, err: ParseKanaError):
         super().__init__(text=err.text, error_name=err.errname, error_args=err.kwargs)

voicevox_engine/engine_manifest.py

@@ -71,10 +71,10 @@ class UpdateInfo(BaseModel):
     エンジンのアップデート情報
     """
 
-    version: str = Field(title="エンジンのバージョン名")
-    descriptions: list[str] = Field(title="アップデートの詳細についての説明")
+    version: str = Field(description="エンジンのバージョン名")
+    descriptions: list[str] = Field(description="アップデートの詳細についての説明")
     contributors: list[str] | SkipJsonSchema[None] = Field(
-        default=None, title="貢献者名"
+        default=None, description="貢献者名"
     )
 
 
@@ -83,40 +83,40 @@ class LicenseInfo(BaseModel):
     依存ライブラリのライセンス情報
     """
 
-    name: str = Field(title="依存ライブラリ名")
+    name: str = Field(description="依存ライブラリ名")
     version: str | SkipJsonSchema[None] = Field(
-        default=None, title="依存ライブラリのバージョン"
+        default=None, description="依存ライブラリのバージョン"
     )
     license: str | SkipJsonSchema[None] = Field(
-        default=None, title="依存ライブラリのライセンス名"
+        default=None, description="依存ライブラリのライセンス名"
     )
-    text: str = Field(title="依存ライブラリのライセンス本文")
+    text: str = Field(description="依存ライブラリのライセンス本文")
 
 
 class SupportedFeatures(BaseModel):
     """
     エンジンが持つ機能の一覧
     """
 
-    adjust_mora_pitch: bool = Field(title="モーラごとの音高の調整")
-    adjust_phoneme_length: bool = Field(title="音素ごとの長さの調整")
-    adjust_speed_scale: bool = Field(title="全体の話速の調整")
-    adjust_pitch_scale: bool = Field(title="全体の音高の調整")
-    adjust_intonation_scale: bool = Field(title="全体の抑揚の調整")
-    adjust_volume_scale: bool = Field(title="全体の音量の調整")
+    adjust_mora_pitch: bool = Field(description="モーラごとの音高の調整")
+    adjust_phoneme_length: bool = Field(description="音素ごとの長さの調整")
+    adjust_speed_scale: bool = Field(description="全体の話速の調整")
+    adjust_pitch_scale: bool = Field(description="全体の音高の調整")
+    adjust_intonation_scale: bool = Field(description="全体の抑揚の調整")
+    adjust_volume_scale: bool = Field(description="全体の音量の調整")
     adjust_pause_length: bool | SkipJsonSchema[None] = Field(
-        default=None, title="句読点などの無音時間の調整"
+        default=None, description="句読点などの無音時間の調整"
     )
-    interrogative_upspeak: bool = Field(title="疑問文の自動調整")
+    interrogative_upspeak: bool = Field(description="疑問文の自動調整")
     synthesis_morphing: bool = Field(
-        title="2種類のスタイルでモーフィングした音声を合成"
+        description="2種類のスタイルでモーフィングした音声を合成"
     )
-    sing: bool | SkipJsonSchema[None] = Field(default=None, title="歌唱音声合成")
+    sing: bool | SkipJsonSchema[None] = Field(default=None, description="歌唱音声合成")
     manage_library: bool | SkipJsonSchema[None] = Field(
-        default=None, title="音声ライブラリのインストール・アンインストール"
+        default=None, description="音声ライブラリのインストール・アンインストール"
     )
     return_resource_url: bool | SkipJsonSchema[None] = Field(
-        default=None, title="speaker_info・singer_infoのリソースをURLで返送"
+        default=None, description="speaker_info・singer_infoのリソースをURLで返送"
     )
 
 
@@ -129,21 +129,23 @@ class EngineManifest(BaseModel):
     エンジン自体に関する情報
     """
 
-    manifest_version: str = Field(title="マニフェストのバージョン")
-    name: EngineName = Field(title="エンジン名")
-    brand_name: BrandName = Field(title="ブランド名")
-    uuid: str = Field(title="エンジンのUUID")
-    url: str = Field(title="エンジンのURL")
-    icon: str = Field(title="エンジンのアイコンをBASE64エンコードしたもの")
-    default_sampling_rate: int = Field(title="デフォルトのサンプリング周波数")
-    frame_rate: float = Field(title="エンジンのフレームレート")
-    terms_of_service: str = Field(title="エンジンの利用規約")
-    update_infos: list[UpdateInfo] = Field(title="エンジンのアップデート情報")
-    dependency_licenses: list[LicenseInfo] = Field(title="依存関係のライセンス情報")
+    manifest_version: str = Field(description="マニフェストのバージョン")
+    name: EngineName = Field(description="エンジン名")
+    brand_name: BrandName = Field(description="ブランド名")
+    uuid: str = Field(description="エンジンのUUID")
+    url: str = Field(description="エンジンのURL")
+    icon: str = Field(description="エンジンのアイコンをBASE64エンコードしたもの")
+    default_sampling_rate: int = Field(description="デフォルトのサンプリング周波数")
+    frame_rate: float = Field(description="エンジンのフレームレート")
+    terms_of_service: str = Field(description="エンジンの利用規約")
+    update_infos: list[UpdateInfo] = Field(description="エンジンのアップデート情報")
+    dependency_licenses: list[LicenseInfo] = Field(
+        description="依存関係のライセンス情報"
+    )
     supported_vvlib_manifest_version: str | SkipJsonSchema[None] = Field(
-        default=None, title="エンジンが対応するvvlibのバージョン"
+        default=None, description="エンジンが対応するvvlibのバージョン"
     )
-    supported_features: SupportedFeatures = Field(title="エンジンが持つ機能")
+    supported_features: SupportedFeatures = Field(description="エンジンが持つ機能")
 
 
 def load_manifest(manifest_path: Path) -> EngineManifest:

voicevox_engine/library/model.py

@@ -14,21 +14,23 @@ class LibrarySpeaker(BaseModel):
     音声ライブラリに含まれる話者の情報
     """
 
-    speaker: Speaker = Field(title="話者情報")
-    speaker_info: SpeakerInfo = Field(title="話者の追加情報")
+    speaker: Speaker = Field(description="話者情報")
+    speaker_info: SpeakerInfo = Field(description="話者の追加情報")
 
 
 class BaseLibraryInfo(BaseModel):
     """
     音声ライブラリの情報
     """
 
-    name: str = Field(title="音声ライブラリの名前")
-    uuid: str = Field(title="音声ライブラリのUUID")
-    version: str = Field(title="音声ライブラリのバージョン")
-    download_url: str = Field(title="音声ライブラリのダウンロードURL")
-    bytes: int = Field(title="音声ライブラリのバイト数")
-    speakers: list[LibrarySpeaker] = Field(title="音声ライブラリに含まれる話者のリスト")
+    name: str = Field(description="音声ライブラリの名前")
+    uuid: str = Field(description="音声ライブラリのUUID")
+    version: str = Field(description="音声ライブラリのバージョン")
+    download_url: str = Field(description="音声ライブラリのダウンロードURL")
+    bytes: int = Field(description="音声ライブラリのバイト数")
+    speakers: list[LibrarySpeaker] = Field(
+        description="音声ライブラリに含まれる話者のリスト"
+    )
 
 
 # 今後InstalledLibraryInfo同様に拡張する可能性を考え、モデルを分けている
@@ -45,18 +47,18 @@ class InstalledLibraryInfo(BaseLibraryInfo):
     インストール済み音声ライブラリの情報
     """
 
-    uninstallable: bool = Field(title="アンインストール可能かどうか")
+    uninstallable: bool = Field(description="アンインストール可能かどうか")
 
 
 class VvlibManifest(BaseModel):
     """
     vvlib(VOICEVOX Library)に関する情報
     """
 
-    manifest_version: StrictStr = Field(title="マニフェストバージョン")
-    name: StrictStr = Field(title="音声ライブラリ名")
-    version: StrictStr = Field(title="音声ライブラリバージョン")
-    uuid: StrictStr = Field(title="音声ライブラリのUUID")
-    brand_name: StrictStr = Field(title="エンジンのブランド名")
-    engine_name: StrictStr = Field(title="エンジン名")
-    engine_uuid: StrictStr = Field(title="エンジンのUUID")
+    manifest_version: StrictStr = Field(description="マニフェストバージョン")
+    name: StrictStr = Field(description="音声ライブラリ名")
+    version: StrictStr = Field(description="音声ライブラリバージョン")
+    uuid: StrictStr = Field(description="音声ライブラリのUUID")
+    brand_name: StrictStr = Field(description="エンジンのブランド名")
+    engine_name: StrictStr = Field(description="エンジン名")
+    engine_uuid: StrictStr = Field(description="エンジンのUUID")

voicevox_engine/metas/Metas.py

@@ -16,11 +16,11 @@ class SpeakerStyle(BaseModel):
     話者のスタイル情報
     """
 
-    name: str = Field(title="スタイル名")
-    id: StyleId = Field(title="スタイルID")
+    name: str = Field(description="スタイル名")
+    id: StyleId = Field(description="スタイルID")
     type: StyleType = Field(
         default="talk",
-        title=(
+        description=(
             "スタイルの種類。"
             "talk:音声合成クエリの作成と音声合成が可能。"
             "singing_teacher:歌唱音声合成用のクエリの作成が可能。"
@@ -36,8 +36,10 @@ class SpeakerSupportedFeatures(BaseModel):
     """
 
     permitted_synthesis_morphing: Literal["ALL", "SELF_ONLY", "NOTHING"] = Field(
-        title="モーフィング機能への対応",
-        description="'ALL' は「全て許可」、'SELF_ONLY' は「同じ話者内でのみ許可」、'NOTHING' は「全て禁止」",
+        description=(
+            "モーフィング機能への対応。"
+            "'ALL' は「全て許可」、'SELF_ONLY' は「同じ話者内でのみ許可」、'NOTHING' は「全て禁止」"
+        ),
         default="ALL",
     )
 
@@ -47,12 +49,12 @@ class Speaker(BaseModel):
     話者情報
     """
 
-    name: str = Field(title="名前")
-    speaker_uuid: str = Field(title="話者のUUID")
-    styles: list[SpeakerStyle] = Field(title="スタイルの一覧")
-    version: str = Field(title="話者のバージョン")
+    name: str = Field(description="名前")
+    speaker_uuid: str = Field(description="話者のUUID")
+    styles: list[SpeakerStyle] = Field(description="スタイルの一覧")
+    version: str = Field(description="話者のバージョン")
     supported_features: SpeakerSupportedFeatures = Field(
-        title="話者の対応機能", default_factory=SpeakerSupportedFeatures
+        description="話者の対応機能", default_factory=SpeakerSupportedFeatures
     )
 
 
@@ -61,16 +63,16 @@ class StyleInfo(BaseModel):
     スタイルの追加情報
     """
 
-    id: StyleId = Field(title="スタイルID")
+    id: StyleId = Field(description="スタイルID")
     icon: str = Field(
-        title="このスタイルのアイコンをbase64エンコードしたもの、あるいはURL"
+        description="このスタイルのアイコンをbase64エンコードしたもの、あるいはURL"
     )
     portrait: str | SkipJsonSchema[None] = Field(
         default=None,
-        title="このスタイルの立ち絵画像をbase64エンコードしたもの、あるいはURL",
+        description="このスタイルの立ち絵画像をbase64エンコードしたもの、あるいはURL",
     )
     voice_samples: list[str] = Field(
-        title="サンプル音声をbase64エンコードしたもの、あるいはURL"
+        description="サンプル音声をbase64エンコードしたもの、あるいはURL"
     )
 
 
@@ -79,6 +81,8 @@ class SpeakerInfo(BaseModel):
     話者の追加情報
     """
 
-    policy: str = Field(title="policy.md")
-    portrait: str = Field(title="立ち絵画像をbase64エンコードしたもの、あるいはURL")
-    style_infos: list[StyleInfo] = Field(title="スタイルの追加情報")
+    policy: str = Field(description="policy.md")
+    portrait: str = Field(
+        description="立ち絵画像をbase64エンコードしたもの、あるいはURL"
+    )
+    style_infos: list[StyleInfo] = Field(description="スタイルの追加情報")

voicevox_engine/model.py

@@ -18,25 +18,25 @@ class AudioQuery(BaseModel):
     音声合成用のクエリ
     """
 
-    accent_phrases: list[AccentPhrase] = Field(title="アクセント句のリスト")
-    speedScale: float = Field(title="全体の話速")
-    pitchScale: float = Field(title="全体の音高")
-    intonationScale: float = Field(title="全体の抑揚")
-    volumeScale: float = Field(title="全体の音量")
-    prePhonemeLength: float = Field(title="音声の前の無音時間")
-    postPhonemeLength: float = Field(title="音声の後の無音時間")
+    accent_phrases: list[AccentPhrase] = Field(description="アクセント句のリスト")
+    speedScale: float = Field(description="全体の話速")
+    pitchScale: float = Field(description="全体の音高")
+    intonationScale: float = Field(description="全体の抑揚")
+    volumeScale: float = Field(description="全体の音量")
+    prePhonemeLength: float = Field(description="音声の前の無音時間")
+    postPhonemeLength: float = Field(description="音声の後の無音時間")
     pauseLength: float | None = Field(
         default=None,
-        title="句読点などの無音時間。nullのときは無視される。デフォルト値はnull",
+        description="句読点などの無音時間。nullのときは無視される。デフォルト値はnull",
     )
     pauseLengthScale: float = Field(
-        default=1, title="句読点などの無音時間（倍率）。デフォルト値は1"
+        default=1, description="句読点などの無音時間（倍率）。デフォルト値は1"
     )
-    outputSamplingRate: int = Field(title="音声データの出力サンプリングレート")
-    outputStereo: bool = Field(title="音声データをステレオ出力するか否か")
+    outputSamplingRate: int = Field(description="音声データの出力サンプリングレート")
+    outputStereo: bool = Field(description="音声データをステレオ出力するか否か")
     kana: str | SkipJsonSchema[None] = Field(
         default=None,
-        title="[読み取り専用]AquesTalk 風記法によるテキスト。音声合成用のクエリとしては無視される",
+        description="[読み取り専用]AquesTalk 風記法によるテキスト。音声合成用のクエリとしては無視される",
     )
 
     def __hash__(self) -> int:

voicevox_engine/morphing/model.py

@@ -8,6 +8,6 @@
 
 
 class MorphableTargetInfo(BaseModel):
-    is_morphable: bool = Field(title="指定した話者に対してモーフィングの可否")
+    is_morphable: bool = Field(description="指定した話者に対してモーフィングの可否")
     # FIXME: add reason property
-    # reason: str | None = Field(title="is_morphableがfalseである場合、その理由")
+    # reason: str | None = Field(description="is_morphableがfalseである場合、その理由")

voicevox_engine/preset/model.py

@@ -15,17 +15,19 @@ class Preset(BaseModel):
     プリセット情報
     """
 
-    id: int = Field(title="プリセットID")
-    name: str = Field(title="プリセット名")
-    speaker_uuid: str = Field(title="話者のUUID")
-    style_id: StyleId = Field(title="スタイルID")
-    speedScale: float = Field(title="全体の話速")
-    pitchScale: float = Field(title="全体の音高")
-    intonationScale: float = Field(title="全体の抑揚")
-    volumeScale: float = Field(title="全体の音量")
-    prePhonemeLength: float = Field(title="音声の前の無音時間")
-    postPhonemeLength: float = Field(title="音声の後の無音時間")
+    id: int = Field(description="プリセットID")
+    name: str = Field(description="プリセット名")
+    speaker_uuid: str = Field(description="話者のUUID")
+    style_id: StyleId = Field(description="スタイルID")
+    speedScale: float = Field(description="全体の話速")
+    pitchScale: float = Field(description="全体の音高")
+    intonationScale: float = Field(description="全体の抑揚")
+    volumeScale: float = Field(description="全体の音量")
+    prePhonemeLength: float = Field(description="音声の前の無音時間")
+    postPhonemeLength: float = Field(description="音声の後の無音時間")
     pauseLength: float | SkipJsonSchema[None] = Field(
-        default=None, title="句読点などの無音時間"
+        default=None, description="句読点などの無音時間"
+    )
+    pauseLengthScale: float = Field(
+        default=1, description="句読点などの無音時間（倍率）"
     )
-    pauseLengthScale: float = Field(default=1, title="句読点などの無音時間（倍率）")