swaggerの仕様の確認にOpenAPISpecのrepositoryのjsonschemaを信用しない方が良い

swaggerの仕様の確認にOpenAPISpecのrepositoryのjsonschemaを信用しない方が良い。

はじめに

swaggerのspecはOpenAPI-Specificationとしてrepositoryがある。

このrepositoryの中に仕様自体のドキュメントもある。ところで、swagger spec(OAS)自体のjsonschemaもここに用意されているのだけれど。これがメンテされてなくて信用できないという話

nullableについて

nullを許容するschemaをどのように書くかという話がある。このあたりの話は以下のissueを見るとわかる

• add "null value support" in spec? · Issue #229 · OAI/OpenAPI-Specification

結論から言うと以下の様になっている。

• OAS2.0(swagger spec)において、nullを許可する値の指定を行う方法は用意されていない
• (jsonschemaのsubsetと言われているものの、jsonschemaでnullを許可する方法自体はswagger spec的には正しくない)
• 幾つかのswagger用のパッケージでは x-nullable という属性を利用している

jsonschemaでnullを許可する方法

通常は以下の様に書く。typeに配列を指定するかoneOfを使う。

nullableString:
  type:
    - string
    - null
nullableString2:
  oneOf:
    - type: string
    - type: null

これらの方法はswagger的には良くないらしい。通常、jsonschemaではtypeの属性には配列を指定できるのだけれど。swaggerでは許していない。そもそもtypeにnull型が存在しないらしい(だからといってstringがnullも含んでいるというわけではない)。

しかもこれらがつらいのは、typeに配列を指定する方法が許可されないというのが実際の仕様には明記されていないものの暗黙の了解として存在するものだったりするところ(先程あげたissueを読むと書いてあったりする)。

ちなみに次のバージョンの仕様(OAS3.0)ではnullは使えないということが明記される様になった。

まとめると

• swaggerに type=null は存在しない
• swaggerに oneOf は存在しない
• swaggerでは typeに配列を書くことを許可していない

ということになるはずなのだけれど。冒頭であげたjsonschemaはメンテされていないのでただただjsonschemaのtypeへのリンクになっているし。つまるところnullも存在すれば配列での指定も許されるというようになっている。以下のような定義なので。

{
  "definitions": {
        "type": {
            "anyOf": [
                { "$ref": "#/definitions/simpleTypes" },
                {
                    "type": "array",
                    "items": { "$ref": "#/definitions/simpleTypes" },
                    "minItems": 1,
                    "uniqueItems": true
                }
            ]
        },
        "simpleTypes": {
            "enum": [ "array", "boolean", "integer", "null", "number", "object", "string" ]
        },
  }
}

ちなみにOAS3.0からはnullableという属性が新たに追加された。 nullable=true だとnull許可ということになる。こういう感じ。

definitions:
  nullableString3:
    type: string
    nullable: true