title | emoji | type | topics | published | publication_name | ||||
---|---|---|---|---|---|---|---|---|---|
OpenAPI + ReDocでSchema定義を自動でドキュメント化する |
📑 |
tech |
|
true |
pytokyo |
OpenAPIを使ったAPI仕様書のドキュメント化はReDocが便利ですが、ひとつ大きな問題があります。Schema定義を自動でドキュメント化できないんですね。
自動ではできないですが、ドキュメント化する方法はあります。
tags:
- name: pet_model
x-displayName: The Pet Model
description: |
<SchemaDefinition schemaRef="#/components/schemas/Pet" />
- name: store_model
x-displayName: The Order Model
description: |
<SchemaDefinition schemaRef="#/components/schemas/Order" exampleRef="#/components/examples/Order" showReadOnly={true} showWriteOnly={true} />
x-tagGroups:
- name: Models
tags:
- pet_model
- store_model
tags
のアイテムのdescription
に<SchemaDefinition schemaRef="" />
を入れると、ドキュメントに書き出されます。
description: |
## Pet
<SchemaDefinition schemaRef="#/components/schemas/Pet" />
このように見出し2
を入れておけば、左ペインのメニューに「Pet」を表示できます。
<SchemaDefinition schemaRef="" />
が追加されたあたりの経緯はReDocのIssueで確認できます。ディスカッションを見ても、自動化の目処は立っていなさそうです。
必要なモデルを毎回手で書くのはかなり辛いので、自動でまとめるCLIツールを作りました。
OpenAPI Redoc Schema Definition - dforest/openapi-redoc-schema-def
これは、指定したタグがついたSchema定義をtags
のdescription
に以下の形でまとめます。
tags:
- name: model
## Hoge
<SchemaDefinition schemaRef="#/components/schemas/Hoge" />
実行にはPython3の実行環境が必要です。まだパッケージ化してないので、GitHubからソースを取得してインストールしてください。
pip install git+https://github.com/dforest/openapi-redoc-schema-def
openapi-redoc-schema-def --path [Path to yaml] --tags [Tags for schema component(s)]
--path [Path to yaml]
にOpenAPIのYAMLを指定します。--tags [Tags for schema component(s)]
にまとめたいタグを指定します。タグはスペース区切りで複数指定できます。
自分用に簡単に作っただけなので、足りない機能やバグがあるかもしれません。PRお待ちしています。
ReDocがそもそも複数のYAMLに対応していないので、このopenapi-redoc-schema-def
も複数のYAMLには対応していません。その場合は、分散したYAMLをひとつのYAMLにまとめてから、openapi-redoc-schema-def
を利用する必要があります。
自分はt2y/openapi-ext-tools: extended tools for openapi specを使ってひとつのYAMLにまとめてから、それにたいしてopenapi-redoc-schema-def
を実行しています。