6 ms·

(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 docu

(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.

saosebastiao 10y ago
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.
- gkoberger 10y ago
  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.
  - k_sh 10y ago
    It's worth adding that Swagger 2.0 documents will be losslessly convertible to OAS 3.0.
- darrelmiller 10y ago
  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.
- sv123 10y ago
  Microsoft actually writes a language-specific client generator AutoRest: https://github.com/Azure/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.
  - darrelmiller 10y ago
    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.
- wing328hk 10y ago
  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 https://github.com/swagger-api/swagger-codegen [2] https://github.com/swagger-api/swagger-parser https://github.com/swagger-api/swagger-parser
pvg 10y ago
What does 'OpenAPI 3 now specifics YAML is 1.2' mean?
- gkoberger 10y ago
  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.
  - pvg 10y ago
    I see, maybe it should say 'specifies' and/or whatever other edits needed to make that read like English.
    - darrelmiller 10y ago
      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.
      - deleted 10y ago
        [deleted]
darrelmiller 10y ago
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 :-)
- jaequery 10y ago
  I second this, I was confused too.
simooooo 10y ago
Have they fixed the very slow swagger-ui project yet?
fcanela 10y ago
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.

saosebastiao 10y ago

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.

gkoberger 10y ago
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.
- k_sh 10y ago
  It's worth adding that Swagger 2.0 documents will be losslessly convertible to OAS 3.0.
darrelmiller 10y ago
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.
sv123 10y ago
Microsoft actually writes a language-specific client generator AutoRest: https://github.com/Azure/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.
- darrelmiller 10y ago
  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.
wing328hk 10y ago
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 https://github.com/swagger-api/swagger-codegen [2] https://github.com/swagger-api/swagger-parser https://github.com/swagger-api/swagger-parser

pvg 10y ago

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

gkoberger 10y ago
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.
- pvg 10y ago
  I see, maybe it should say 'specifies' and/or whatever other edits needed to make that read like English.
  - darrelmiller 10y ago
    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.
    - deleted 10y ago
      [deleted]

darrelmiller 10y ago

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

jaequery 10y ago
I second this, I was confused too.

simooooo 10y ago

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

fcanela 10y ago

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.