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ではこれを利用できない)。

ところで、allOfでdescriptionが重複したときには後勝ち先勝ちなどあるのだろうか?


  1. たぶん野良なのではないか?公式ではないと思う(?)