5 ms·

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

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

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