OpenAPI + ReDocでSchema定義を自動でドキュメント化する
ReDocはSchema定義を自動でドキュメント化できない
OpenAPIを使ったAPI仕様書のドキュメント化はReDocが便利ですが、ひとつ大きな問題があります。Schema定義を自動でドキュメント化できないんですね。
自動ではできないですが、ドキュメント化する方法はあります。
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ツールを作りました。
Schema定義を自動でまとめる
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お待ちしています。
複数のYAMLがある場合
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
を実行しています。
Discussion