Documentation part
AWS API GatewayのREST APIはOpenAPIに準拠したドキュメントの生成もサポートされている *1。
API GatewayのREST APIはリソースやメソッドなどの部品から成る。特別な定義なしでも、これらAWS上のリソースが持つ各種プロパティからデフォルトでまあまあ良い感じのドキュメントは出力される。
しかしデフォルトではOpenAPI 3が必須とするいくつかのプロパティ *2 が出力されなかったり、実用的なAPIドキュメントに含めたい内容が欠けていたりする。
API GatewayはREST APIの各構成部品に対して追加のドキュメンテーション情報を持つことができ、それらはdocumentation partと呼ばれる。
refs. Documenting REST APIs - Amazon API Gateway
location
documentation partのインスタンスは自身がAPI, オーソライザー、リソース、メソッド、などどの部品に対するドキュメントなのかを指す情報としてlocationを持つ。
refs. Location of a documentation part - Representation of API documentation in API Gateway - Amazon API Gateway
locationは各部品ごとに必須・利用可能なフィールドが異なっておりValid location fields of DocumentationPart - Representation of API documentation in API Gateway - Amazon API Gatewayにまとめられている。
properties
documentation partはpropertiesという任意のオブジェクトを持つことができ、これがOpenAPI spec.に現れる。
このpropertiesはOpenAPI spec.に準拠していないといけないとドキュメントでも言及されている。
refs. Content of a documentation part - Representation of API documentation in API Gateway - Amazon API Gateway
即ち仕様で定められたプロパティか、あるいは x- で始まる任意の拡張プロパティのみが使える。
実体への対応
どうもdocumentation partは対応する部品の実体なしにエクスポート結果には現れないようだった。
これは公式ドキュメントの記述を引いたわけではなく、挙動からの推測になる。
HTTPメソッド定義がなければそれをlocationに持つdocumentation partが現れないというのは想像しやすいけれど、自分はパスパラメータのdocumentation partが出てこなくてしばらくハマった。
現時点ではパスパラメータのdocumentation partはrequestParametersに含めないと現れないようだった。
これは恐らくクエリパラメータやヘッダについてもそう言えると思う。
documentation version
ここまでで定義してきたdocumentation partを反映するには新しいdocumentation versionを発行しなければならない。
APIドキュメントの版を指し、新しい版が最新のdocumentation partを含む。
documentation partだけCloudFormationなどで定義してもdocumention versionを新しく作成しなければ参照できない。
