Enhancement: Support for 'OpenAPI Specification version 3.0'

[mrenvoize]

This is still in technical draft at the time of writing, with a 'first Implementor Draft' due for release on February 28th 2017.

https://www.openapis.org/blog/2017/01/24/a-new-year-a-new-specification give's a broad overview.

Corresponding issue for Mojolicious::Plugin::OpenAPI jhthorsen/mojolicious-plugin-openapi#20

[jhthorsen]

Where is the draft? All I could find is https://github.com/OAI/OpenAPI-Specification/blob/OpenAPI.next/versions/3.0.md

[mrenvoize]

I'm not sure there's more than what you linked to there yet @jhthorsen.

This issue is more of a placeholder to remind me/us to take a look when they do their draft implementor release on 28th Feb

[jhthorsen]

Aha! Cool 👍

@tyldum: You have to wait I guess.

[webron]

We have released the draft of the spec, but not a schema for it yet. That's on my to do list, but no ETA yet. I'll check with the team how we'll announce it, potentially it'll be a tweet (for better or worse).

[jhthorsen]

Awesome! I know many of my users of my libraries are eager to use the new version. I just hope I can use most of my code, haha.

Thanks for all the work. Using OpenAPI has really helped me a lot!

[webron]

You should check the release notes to get a sense of what's changed. I do think we made a lot of positive changes. We tried to keep things pragmatic still, but with the (fair) requests to support some things, some of the structures got more complex. We did try to make things more consistent though to make implementations easier.

We'd appreciate feedback about the spec. This is why it's called an Implementer's Draft - so implementations start coming in, and we'll see what's unclear in the docs or maybe what features simply don't make sense.

[mrenvoize]

http://openapi-specification-visual-documentation.apihandyman.io might be helpful in spotting the differences when we come to it.

[mrenvoize]

@webron any update on there being a json-schema for this new version yet?

[webron]

We currently have two proposals but have not made a decision which one is going to be used. They are in PRs on the OAS repository if you want to check them out. I imagine we'll make a decision in the upcoming couple of weeks.

[jberger]

@webron interesting that it now seems that the release date for 3.0.0 was 2017-07-26, ie, before that previous comment. Whatever the timeline, is it safe to say that 3.0.0 is now stabile?

[jberger]

Indeed the release blog post was from before the comment too: https://swagger.io/blog/announcing-openapi-3-0/

[webron]

@jberger the spec has been released and is stable (we just released 3.0.1). However, the previous comment refers to the JSON Schema, and the status on that has not changed.

[jberger]

Ah thank you. My mistake.

[Pilat66]

Whats about OpenAPI 3 ?

[jhthorsen]

@Pilat66: I don't understand your question.

[Pilat66]

@jhthorsen : Will you support OpenAPI version 3?
The openapi-v3 branch was created, but there is no activity in it.

[jhthorsen]

I will some day, when the spec is ready and I find time to implement it, or if someone sends a PR.

[mohawk2]

@Pilat66 It seems to me that until @webron tells us there is a JSON Schema for OpenAPI 3 specs, we can't even automatically tell whether a given spec is valid OAI 3! So if you were to encourage them... :-)

[darrelmiller]

@mohawk2 Even when you have a JSON Schema, you will not be able to tell if the spec is valid. JSON Schema cannot express some of the constraints the spec defines.

[mohawk2]

@darrelmiller I hear you, but it will be a good part of the journey, no?

[Pilat66]

I do not understand. OpenAPI2 is almost impossible to use - it is not supported by external tools, SmartBear removed it from Eclipse and current versions of its utilities, and made changes in versions that supported version 2, after which extensions such as 'null' cause errors. Why not develop OpenAPI3 - all go to it. It is not possible to write services that will not only be called from Mojolicious.

[webron]

@Pilat66 say what now? The majority of the tools out there support OpenAPI2 and not OpenAPI3 still (including the major vendors such as Microsoft, Google, IBM, Amazon and so on).

SmartBear removed what from Eclipse? I work on the open source tools at SmartBear and I'm not aware of any tool we have/had for eclipse, definitely not one that was removed. If you give me more details, I'll be happy to look into it, as there's no reason to have anything removed.

As for the null - not sure what you're referring to.

[jberger]

Currently JSON::Validator relies on interpreting a json schema file to do most of the work of validating OpenAPI (v2) specs. The OpenAPI schema file itself is a json schema file, as is your api spec. The validator for the json schema file is already written, the code that imports the v2 spec and overrides minor bits of code to be semantically correct are written on top of that.

To write a bespoke OpenAPI v3 validator without an json schema spec would mean writing an entirely new module. As I'm sure you can understand, @Pilat66, casually suggesting that we rewrite an entire module for your benefit is not a very fitting discussion point. As such, I'll assume you didn't understand that and continue with this conversation, which we do very much care about.

[jhthorsen]

I'm closing and locking this issue, because I'm embarrassed by some of the comments issued against the OpenAPI team and @webron.

While we all eagerly await the arrival of a v3 spec, I for one appreciate that the OpenAPI team takes the time to ensure a good new major version of the specification.

For everyone else who wants v3 support in JSON::Validator: This will be implemented, once the specification is ready.