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.

Uh oh!

Support OpenAPI version 3.0 #165

Description

Metadata

Metadata

Assignees

Labels

Type

Projects

Milestone

Relationships

Development

Issue actions