Welcoming OpenAPI 3.0 to Apiary
By Kyle (@kylefuller, kyle.fuller@oracle.com) on 06 Feb 2019
I’m delighted to announce experimental support for OpenAPI 3.0 in Apiary. OpenAPI 3 is the new major version of the OpenAPI Specification, the successor to OpenAPI 2 (or formerly known as Swagger 2).
While we are not yet supporting all of the new features added OAS 3 such as callbacks and links , we’ve built a solid foundation of our parser which will allow us to incrementally roll out support for new features across our entire product line. Whether it be in our mock server, Dredd, our new documentation renderer or our API Style Guide product.
Our OpenAPI 3 parser is designed with user experience in mind. It brings significant improvements over our OpenAPI 2 parser.
Better Warning and Error Reporting
The most significant difference is the parser is able to emit much clearer warnings and errors when the OpenAPI syntax is not semantically correct. This was a large source of user frustration for our OpenAPI 2 users. With OpenAPI 2 you’d often get hard to understand warnings or errors due to the OpenAPI 2 parser relying on the JSON Schema from OpenAPI Initiative as the base of validations. JSON Schema validations often produce unclear error messages.
We’ve taken validation completely into our own hands so we can have far greater control over the user experience.
As an example, if you miss a required in property for a Parameter Object in
OpenAPI 2, you’ll often see a confusing error such as the following:
Data does not match any schemas from ‘oneOf’
You’ll see the exact same error message if the value of in is not a permitted
value or is not a string.
Whereas for similar semantic issues, our OpenAPI 3 parser will emit clearer errors:
‘Parameter Object’ is missing required property ‘in’
‘Parameter Object’ ‘in’ must be either ‘query’, ‘header’, ‘path’ or ‘cookie’”
The state of the errors and warnings in our OpenAPI 2 parser can also fall down
further when you are dealing with referencing as the entire OAS 2 document is
dereferenced (stripped of $ref) up front, which means that the context of an
error can be missing and it can be hard to pin-point the exact line which
caused a parsing error.
Validation Speed
Another key user experience improvement will be with the performance of our new parser in comparison to our OAS 2 parser. We can parse extremely large OAS 3 documents (multiple megabytes) in an order of magnitude faster than we could for OAS 2 so you can get much quicker feedback in our editor.
Try OpenAPI 3.0 Today
You can try OpenAPI 3.0 today in both Apiary and our open source tools such as such as Dredd - see example usage in our GitHub issue#71.
When our OpenAPI 3 support reaches maturity, we will be providing you the ability to create a new API Project in Apiary using OpenAPI 3. In this stage of rollout you can copy in an OpenAPI 3 document into an existing Apiary API Project in the Apiary Editor and our editor will detect and support OAS 3 documents.
We’re building our parser out in the open and we welcome any contributions or feedback however small, whether its improving the wording of our warnings and error messages or providing valuable feedback in our issue tracker.
You can track the current status of supported OAS 3 functionality, we are also publishing a list of the changes we make to our parser so you can keep up to date on further developments.
Try OpenAPI 3 with our new ApiaryUI documentation!