Support OpenAPI version 3.0

[rdehouss]

Hi there,

We're using APISpec with Marshmallow and aiohttp or sanic and it works really great.

There are some new great changes with OpenAPI (version 3) vs Swagger API (version 2).
Any plan to implement Open API version 3?

Thanks

Kind regards,

Raphaël

[zikphil]

+1 for this

[benturnerdev]

+1

[lafrech]

Guys, please use the thumbs up emoticon rather than posting +1 comments. This is just noise for those being notified by email.

If you want to help tackle this issue, you may dig in the OpenAPI 2 and 3 specs to spot differences, or maybe find a "what's new ?" or "migration howto" like this:

https://www.blazemeter.com/blog/whats-new-in-swagger-open-api3

Here's what I noticed, already.

Polymorphism

The use of discriminator has been clarified:

https://github.com/OAI/OpenAPI-Specification/blob/3.0.0/versions/3.0.0.md#composition-and-inheritance-polymorphism

(see this commit.)

I don't think this is a breaking change. AFAIK, there was nothing about this in apispec and anyway, v3 is backwards compatible with v2 IIUC.

Parameter locations

https://github.com/OAI/OpenAPI-Specification/blob/3.0.0/versions/3.0.0.md#parameter-locations

Possible values are "query", "header", "path" or "cookie".

It differs slightly from OpenAPi v2:

https://github.com/OAI/OpenAPI-Specification/blob/3.0.0/versions/2.0.md#fixed-fields-7

Possible values are "query", "header", "path", "formData" or "body".

This may have an impact on __location_map__ in marshmallow swagger extension, which looks like a mix of the two, already:

__location_map__ = {
    'query': 'query',
    'querystring': 'query',
    'json': 'body',
    'headers': 'header',
    'cookies': 'cookie',
    'form': 'formData',
    'files': 'formData',
}

It seems, though, that it is not just about updating that dictionary. From the link above:

The new 'requestBody' attribute supersedes the previous 'formData' parameter type and 'body' attribute and is now more flexible in allowing the specification of different types of content with various media types.

[...]

Examples...

@sloria, any thoughts about v2 vs. v3?

It would be nice if we could maintain a single apispec version rather than two.

• We could be permissive: make apispec compatible with both v2 and v3 and let the user be responsible for the consistency.

• Or we could use a config parameter fo v2 vs. v3 and try to prevent writing v2 specs when v3 is selected and conversely.

A comprehensive list of changes would help. Contributions welcome.

[sloria]

I definitely would like to see support for v3 in apispec. That said, I personally do not need it for work or otherwise, and my time is very limited these days, so it's hard for me to put in the necessary time for this. I welcome any contributions!

Thanks for doing that initial analysis, @lafrech .

• We could be permissive: make apispec compatible with both v2 and v3 and let the user be responsible for the consistency.
• Or we could use a config parameter fo v2 vs. v3 and try to prevent writing v2 specs when v3 is selected and conversely.

I lean toward the former; apispec is generally permissive in what it allows; there aren't a lot of runtime checks for correctness to the OpenAPI spec.

It would be great if OpenAPI v3 could be supported out-of-box without breaking apispec's API.

[lafrech]

I lean toward the former; apispec is generally permissive in what it allows; there aren't a lot of runtime checks for correctness to the OpenAPI spec.

Yes. What I thought, too. Glad that you confirm.

Time limited on my side as well and no need to have this production ready right now.

To potential contributors: listing v2/v3 issues here would be helpful already. Implementation can come in a second phase. On the other hand, small non-breaking patches are acceptable as well. No need to get the whole thing thought and done at once.

[lafrech]

OpenAPI 3.0 introduces writeOnly

https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.0.md#fixed-fields-20

• add writeOnly for load_only fields (typically passwords).

Also, it is acceptable in 3.0 to have a field both required and readOnly, in which case it means it must not be in a request but it is guaranteed to be in a response. In 2.0, required was designed mostly for requests and a field could not be both required and readOnly. OAI/OpenAPI-Specification#228

• Enforce this required/readOnly logic? Let's be permissive and let the user be responsible for that.

[lafrech]

nullable was added to OpenAPI 3: OAI/OpenAPI-Specification#229 (comment).

• Rework Translate allow_none property into x-nullable #109 to use x-nullable in v2 and nullable in v3.