OpenAPI + ReDocでSchema定義を自動でドキュメント化する

ReDocはSchema定義を自動でドキュメント化できない

ReDoc Interactive Demo

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を実行しています。