Hacker News Reader

Comment by gkoberger | Hacker News Reader

(Note: I'm the author, but have nothing to do with the Open API Initiative)

Swagger 2 (current version) got really popular the past few months as a way to document your API. Now, Swagger 3 (er, Open API Spec 3 as it's now known) is about to launch. I had a hard time finding what was new, so we made an example-filled guide that will help with your migrations.

tl;dr: Swagger 3 isn't ready for use yet, and is way more complex but solves a lot of problems with 2.

View on HN

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 :-)

I second this, I was confused too.

The idea of a standardized API documentation format is great. However, the community that surrounds it can't mature with this amount of churn in the standard. Who is going to write a language-specific client generator if the work is obsolete a few weeks later? It would be interesting to know what was so wrong with Swagger2 that we need a new standard.

I'm personally not a huge fan of Swagger, however I don't think you have to worry. Since 2012, there's only been two new versions. It's not exactly a fast-moving spec that will be out of date in a few weeks.

I do believe that Swagger 3 (and the rename) will splinter the community, however I think fixing some of the fundamental issues with Swagger (many of which are enumerated in the blog post) is very important.

It's worth adding that Swagger 2.0 documents will be losslessly convertible to OAS 3.0.

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.

Microsoft actually writes a language-specific client generator AutoRest: https://github.com/Azure/autorest

I believe at this time the majority of the azure sdks are using it, so quite an investment has been made.

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.

Swagger Codegen [1] is a free, open source code generator that works with Swagger 1.2, 2.0 and supports 30+ API clients, 20+ server stubs and API documentations:

- API clients: ActionScript, Bash, C# (.net 2.0, 4.0 or later), C++ (cpprest, Qt5, Tizen), Clojure, Dart, Elixir, Go, Groovy, Haskell, Java (Jersey1.x, Jersey2.x, OkHttp, Retrofit1.x, Retrofit2.x, Feign), Node.js (ES5, ES6, AngularJS with Google Closure Compiler annotations) Objective-C, Perl, PHP, Python, Ruby, Scala, Swift (2.x, 3.x), Typescript (Angular1.x, Angular2.x, Fetch, jQuery, Node)

- Server stubs: C# (ASP.NET Core, NancyFx), Erlang, Go, Haskell, Java (MSF4J, Spring, Undertow, JAX-RS: CDI, CXF, Inflector, RestEasy), PHP (Lumen, Slim, Silex, Zend Expressive), Python (Flask), NodeJS, Ruby (Sinatra, Rails5), Scala (Finch, Scalatra)

- API documentation generators: HTML, Confluence Wiki

Lots of companies are using it in production and the project is very active with 500+ contributors.

Swagger Codegen leverages another open source project "Swagger Parser" [2] to parse the Swagger specification (JSON/YAML) and the parser will later support OpenAPI 3.0 so eventually Swagger Codegen will support Swagger 1.2, 2.0 and OpenAPI 3.0.

[1] https://github.com/swagger-api/swagger-codegen

[2] https://github.com/swagger-api/swagger-parser

Thanks for the article, I loved how they solved the "how do we propertly documment hypermedia APIs" question that I get asked in each Meetup.

I think there is a little error in the article. In the "Request Format" example the request method should be PUT.

What does 'OpenAPI 3 now specifics YAML is 1.2' mean?

Swagger 2 was either YAML or JSON. Since YAML is an evolving standard, OpenAPI 3 just specifies that your YAML should be in YAML 1.2.

Likely a change that won't affect anyone; it's just a clarification.

I see, maybe it should say 'specifies' and/or whatever other edits needed to make that read like English.

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.

Have they fixed the very slow swagger-ui project yet?

Reply on news.ycombinator.com