Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Support OpenAPI version 3.0 #165

Closed
rdehouss opened this issue Nov 2, 2017 · 16 comments

Comments

@rdehouss
Copy link

commented Nov 2, 2017

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

@rdehouss rdehouss changed the title Support OpenAPI Support OpenAPI version 3.0 Nov 2, 2017

@zikphil

This comment has been minimized.

Copy link

commented Nov 16, 2017

+1 for this

@b-turner

This comment has been minimized.

Copy link

commented Nov 20, 2017

+1

@lafrech

This comment has been minimized.

Copy link
Member

commented Nov 21, 2017

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

This comment has been minimized.

Copy link
Member

commented Nov 21, 2017

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

This comment has been minimized.

Copy link
Member

commented Nov 21, 2017

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

This comment has been minimized.

Copy link
Member

commented Mar 24, 2018

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

This comment has been minimized.

Copy link
Member

commented Apr 4, 2018

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

  • Rework #109 to use x-nullable in v2 and nullable in v3.
@lafrech

This comment has been minimized.

Copy link
Member

commented May 14, 2018

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

This comment has been minimized.

Copy link
Member

commented May 14, 2018

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

This comment has been minimized.

Copy link
Member

commented May 16, 2018

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

This comment has been minimized.

Copy link
Member

commented Oct 22, 2018

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 #78)
@sloria

This comment has been minimized.

Copy link
Member

commented Jan 14, 2019

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

@lafrech

This comment has been minimized.

Copy link
Member

commented Jan 14, 2019

Yes. Checked.

@lafrech

This comment has been minimized.

Copy link
Member

commented Feb 1, 2019

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.

@lafrech lafrech closed this Feb 1, 2019

@rshah88

This comment has been minimized.

Copy link

commented May 20, 2019

Is this released ?

@lafrech

This comment has been minimized.

Copy link
Member

commented May 20, 2019

Yes. Since apispec 1.0.0.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Projects
None yet
6 participants
You can’t perform that action at this time.