darrelmiller

The site is back, but I this was a sufficient kick in the ass to finally get the blog moved onto a proper platform.

Well that's embarrassing.

The text is different but the meaning is the same. A GET body must not have an effect on the request/response. i.e. You can have one, but you are not allowed to use it for anything.

We use OpenAPI in many other places too. Azure Logic Apps, Azure API Management, Azure Functions, Azure API Apps, Microsoft Flow, PowerApps. And the list just keeps getting longer. Also, the new Microsoft Docs site is driven off OpenAPI.

We have been having numerous conversations within Microsoft to figure out how to describe Graph API using OpenAPI. The new Links capability helps a lot. Also, the AnyOf support will help with describing URLs with Expand. There are still a bunch of issues to work out.

You are correct that the Swagger name is owned by Smartbear, however, whereas previously Swagger was used to name tooling and the specification, now Swagger only refers to the tooling built by Smartbear. OpenAPI V2 and V3 is the name of just the specification. Saying that they are the same thing causes more confusion than has already been created.

It makes it hard to take advantage of HTTP caches. There is also some redundancy because SOAP has headers and HTTP has headers. Which to use? It also is handy to be able to make idempotent requests, especially over flakey networks.

The one distinction that I think is worth making is that OpenAPI describes HTTP APIs using the semantics of HTTP. Corba and SOAP attempted to be protocol independent. That's much harder to do well. Another good aspect of OpenAPI is that most people who are using it, are starting towards using the definition as the primary design artifact and then letting tooling work on that. Almost no-one designed WSDL or IDL by hand. Focusing on an OpenAPI as a design contract helps developers produce solutions that are more independent of tooling. And that's a good thing.

This issue list on the OpenAPI GitHub repo is full of requests for change. The spec hasn't changed in a long time, and although this is a fairly big change, it shouldn't be a particularly difficult change for tooling folks to adapt to. This isn't a new standard, it's just a new name, with some fixes and some new features.

By declaring conformance to YAML 1.2 and requiring conformance to the JSON Schema ruleset defined in YAML 1.2 we can ensure that any YAML OpenAPI document can be converted into JSON without any loss of information.

OpenAPI V3 now supports AnyOf and OneOf constructs from JSON Schema.

We're not :-)

Yes, we decided to be opinionated and say you can't describe bodies for operations where the spec says bodies have no meaning. The text should be there, but I think the RC0 revision has some formatting issues that is hiding the text.

Hey Gregory, thanks for the article. Would it be possible to change your title to OpenAPI 3 and not Swagger 3.0? Swagger is the name of the tooling produced by Smartbear that supports OpenAPI and they just released new versions of their Swagger tooling, but it's not the same thing as OpenAPI 3.0. Yes I know it is confusing :-)