OpenAPI3

[phadej]

https://www.google.fi/amp/s/blog.readme.io/an-example-filled-guide-to-swagger-3-2/amp/

So... what is the plan?

[fizruk]

At a first glance looks like not much has changed.

Some changes to Schema are interesting, specifically:

• oneOf (or anyOf) can now be used to better represent sum types.
• nullable is something people were asking about.

Otherwise OpenAPI 3.0.0 looks like mostly regrouping/renaming things.

I guess we should fork swagger2 and make a new openapi3 package?
And similarly fork servant-swagger to servant-openapi?

We could support OpenAPI3 within swagger2, but I'm not sure that's a good idea.

In any case, I don't think we're in a hurry since

• OpenAPI 3.0.0 is not released yet;
• there are no UI tools yet AFAICT;
• I don't really see which problems OpenAPI 3.0.0 solves compared to Swagger 2.0.

[daurnimator]

OpenAPI 3.0.0 is not released yet;

OpenAPI 3.0.0 was released in july. https://www.openapis.org/blog/2017/07/26/the-oai-announces-the-openapi-specification-3-0-0

[ThomasCrevoisier]

@fizruk I'm currently using your package in my job and I'll need to be able to use oneOf soon for sum types. Can I help you with the implementation ?

[fizruk]

@ThomasCrevoisier you can certainly fork and add oneOf support.

However, there's a big question on how to fit this change in the current package. If you only add oneOf you end up with something that's neither Swagger 2.0 nor OpenAPI 3.0.0.

I see 3 options to move forward:

• start a new package (say, openapi3);
• add a new top-level module OpenAPI3 to this package, so it has support for both Swagger 2.0 and OpenAPI 3.0.0; we can start this new module with a fork of Swagger modules and just adding oneOf;
• fork this package, add features you specifically need and use the fork in your project.

Unfortunately I don't have enough time or motivation to work on a complete OpenAPI 3.0.0 support. Swagger 2.0 suits my current needs perfectly. Still, I can offer some help if you need it.

Which option above do you prefer?

[phadej]

I think second option is good enough for now, but I'm interested in seeing openapi3 package eventually. I could help with it, but only after a while.

[ThomasCrevoisier]

If I understood correctly Swagger 2.0 is a subset of OpenAPI 3.0.0 ? If so, the second option would be a good transition before having an openapi3 package indeed.

Is there a way to discuss privately ? I would be happy to help but I need to improve my understanding of the codebase and my Haskell skills a bit.

[fizruk]

@ThomasCrevoisier @phadej I have created haskell-swagger2 community in Gitter and invited you. Would Gitter be ok?

[fishtreesugar]

https://github.com/julian-becker/openapi3

[ThomasCrevoisier]

I deeply apologize for my lack of communication on this one. I didn't find the time to tackle this and I find myself lost in generics...

[shinzui]

@fieldstrength Is there a reason why you decided not to submit your fork as a PR? @fizruk Are you still interested in supporting OpenAPI3?

[fisx]

note to self: swagger3 is not strictly more powerful, or at least not quite yet: swagger-api/swagger-ui#4425 (but also OAI/OpenAPI-Specification#1937).