Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

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

Merged
merged 2 commits into from
Jun 27, 2024

Conversation

sabonerune
Copy link
Contributor

内容

OpenAPIのドキュメントをより見やすくします。

#1318 (comment) で分かったことなのですがFieldtitle引数でモデルの要素の説明を書くとSwagger UIでは表示されないことが分かりました。
また、descriptionの方に書くと表示されることが分かりました。

descriptionの方が分かりやすいと思うので変更します。

関連 Issue

スクリーンショット・動画など

変更後のイメージ

  • Redoc
    Redoc
  • Swagger UI
    Swagger UI

その他

APIの動作には影響はないはず。

一部で既にdescriptionを使用している部分があったので改行で対応。

Comment on lines -51 to +52
title="エラー名",
description="|name|description|\n|---|---|\n"
description="エラー名\n\n"
"|name|description|\n|---|---|\n"
Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

既にdescriptionが使用されていたので改行で対応した。

voicevox_engine/metas/Metas.py Outdated Show resolved Hide resolved
Comment on lines +23 to 26
description=(
"スタイルの種類。"
"talk:音声合成クエリの作成と音声合成が可能。"
"singing_teacher:歌唱音声合成用のクエリの作成が可能。"
Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

直接関係はないのだが改行されないので見にくい気がする。

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

そもそもスキーマは別リンクになっていて欲しい気もしますね。。

@sabonerune sabonerune marked this pull request as ready for review June 26, 2024 11:17
@sabonerune sabonerune requested a review from a team as a code owner June 26, 2024 11:18
@sabonerune sabonerune requested review from Hiroshiba and removed request for a team June 26, 2024 11:18
Copy link
Member

@Hiroshiba Hiroshiba left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

LGTM!!

今思ったんですが、そもそも結構見づらいですね。。
画面が広い時に右に表示されるjsonサンプルみたいなのがいらなさそう・・・?(いる人もいるかもだけど。。)

ドキュメント読んだ感じ、設定は色々ありそう。
https://redocly.com/docs/redoc/config

Copy link
Member

@Hiroshiba Hiroshiba left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

マージします!

OpenAPI見るとtitleは自動せいせされてそうですね。
これが最高の形かどうかはわからないけど、とりあえず良くなった・・・はず。

@Hiroshiba Hiroshiba merged commit 5eb440a into VOICEVOX:master Jun 27, 2024
4 checks passed
@sabonerune sabonerune deleted the enh/title-to-description branch June 27, 2024 09:04
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

Successfully merging this pull request may close these issues.

2 participants