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.

[lafrech]

OpenAPI 3 adds TRACE method (OAI/OpenAPI-Specification@c306532).

• Complete VALID_METHODS. If we want this to depend on OpenAPI version, we can make it an attribute of Path. Or declare both VALID_METHODS_OPENAPI_v2 and ..._v3 globals and pick one from the Path instance, so that the globals are still exposed.

[sloria]

we can make it an attribute of Path. Or declare both VALID_METHODS_OPENAPI_v2 and ..._v3 globals and pick one from the Path instance, so that the globals are still exposed.

I don't a strong preference either way, but adding valid_methods as a property on Path seems like better encapsulation.

[lafrech]

In OpenAPI 3, parameter objects are modified: v2, v3.

• In v2, body is a special case, and the parameter definition contains a schema, while for other types, type, format,... are exposed directly. In v3, there is always a schema.

It's a bit more complicated than this, I'm afraid, but that's the rough idea.

This is the reason that line was commented in the tests to allow the test to pass.

Edit: This is fixed. I uncommented the line in the tests (#362) and they pass.

[lafrech]

https://swagger.io/docs/specification/api-host-and-base-path/

In OpenAPI 3.0, you use the servers array to specify one or more base URLs for your API. servers replaces the host, basePath and schemes keywords used in OpenAPI 2.0. Each server has an url and an optional Markdown-formatted description.

This affects code that relies on basePath, like normalize_path (see #78).

• Generalize code relying on basePath (or remove it if possible as suggested in Core path does not support swagger basePath #78)

[sloria]

@lafrech Can your previous comment be checked off, now that we've removed the path normalization code?

[lafrech]

Yes. Checked.

[lafrech]

Looks like we implemented all the changes we identified. Let's close this for now and declare apispec OpenAPIv3 compliant.

If other adaptations are needed, we'll open dedicated issues.

[rshah88]

Is this released ?

[lafrech]

Yes. Since apispec 1.0.0.