OpenAPIの$refにdescriptionをつける苦肉の策
例えば以下のようなschemaがあるとする。このperson中のfather,motherは同じschemaのpersonを参照する形になっている。
{ "components": { "schemas": { "person": { "type": "object", "properties": { "name": { "type": "string" }, "age": { "type": "integer" }, "father": { "$ref": "#/components/schemas/person" }, "mother": { "$ref": "#/components/schemas/person" } } } } }, "openapi": "3.0.0" }
まぁそれはおいておいて、openAPIの仕様的に、Reference Object ($ref
を持った参照部分のこと) はそれ以外のフィールドを持つことができない。
そんなわけで、説明 (description) を追加することができない。こういう時の苦肉の策のメモ。
allOfを使う
allOfを使って以下のように書くことができるかもしれない。これは一応仕様的にもvalidな記述。
--- 00schema/openapi.json 2021-02-10 19:12:24.000000000 +0900 +++ 01schema/openapi.json 2021-02-10 19:42:49.000000000 +0900 @@ -11,14 +11,20 @@ "type": "integer" }, "father": { - "$ref": "#/components/schemas/person" + "allOf": [ + {"$ref": "#/components/schemas/person"}, + {"description": "父親"} + ] }, "mother": { - "$ref": "#/components/schemas/person" + "allOf": [ + {"$ref": "#/components/schemas/person"}, + {"description": "母親"}, + ] } } }
問題は、適切に解釈してくれるツールが少ないことですね。。
ちなみに
ちなみに、apiguruでAWSのECSのopenapi.json1を覗いたときに存在を思い出した。
追記
そして、また、思い出したけれど。JSONSchemaのこのissueに繋がる
追記
(なんとなくissueを眺めてしまった)
最終的にallOfとadditionalPropretiesの長い議論になり、この辺の話は、unevaluatedProperties の導入に繋がるみたい(openAPIではこれを利用できない)。
- https://github.com/json-schema-org/json-schema-spec/issues/556
- http://json-schema.org/draft/2019-09/json-schema-core.html#rfc.section.9.3.2.4
ところで、allOfでdescriptionが重複したときには後勝ち先勝ちなどあるのだろうか?
-
たぶん野良なのではないか?公式ではないと思う(?)↩