18 ms·
A Visual Guide to What's New in Swagger 3.0
- gkoberger 10y ago(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 agoThe 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 agoI'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 agoIt's worth adding that Swagger 2.0 documents will be losslessly convertible to OAS 3.0.
- darrelmiller 10y agoThis 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 agoMicrosoft 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 agoWe 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 agoSwagger 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 agoWhat does 'OpenAPI 3 now specifics YAML is 1.2' mean?
- gkoberger 10y agoSwagger 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 agoI see, maybe it should say 'specifies' and/or whatever other edits needed to make that read like English.
- darrelmiller 10y agoBy 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 agoHey 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 agoI second this, I was confused too.
- simooooo 10y agoHave they fixed the very slow swagger-ui project yet?
- fcanela 10y agoThanks 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.
- gnidan 10y agoIs there any plan to expand the support for runtime polymorphism in 3.0?
- darrelmiller 10y agoOpenAPI V3 now supports AnyOf and OneOf constructs from JSON Schema.
- Dunedan 10y ago> Lastly, you’re no longer allowed to define a response for GET and DELETE (which matches how RESTful APIs work). I get that part about the DELETE, but no response for GET sounds odd. As I couldn't find anything in the spec RC: Is there further information available regarding that?
- smizell 10y agoTotal guess, but they may mean request bodies instead of response since GET and DELETE normally don't have request bodies. However, I'm not sure there is a definitive answer on if that's true from an HTTP perspective. I also couldn't find it in a skimming of the OpenAPI 3.0 spec. In the end, REST [1] itself does not prescribe either condition and the HTTP 1.1 [2] spec doesn't either. > A payload within a GET request message has no defined semantics; sending a payload body on a GET request might cause some existing implementations to reject the request. [1] https://www.ics.uci.edu/~fielding/pubs/dissertation/rest_arch_style.htm https://www.ics.uci.edu/~fielding/pubs/dissertation/rest_arc... [2] https://tools.ietf.org/html/rfc7231#section-4.3.1 https://tools.ietf.org/html/rfc7231#section-4.3.1
- johnhenry 10y agoI tend to agree with the interpretation given here: http://stackoverflow.com/questions/978061/http-get-with-request-body http://stackoverflow.com/questions/978061/http-get-with-requ... -- that if a GET request contains a body, the server should ignore it in order to stay compliant with the spec.
- gkoberger 10y agoSorry, typo. Should be "request bodies"!
- darrelmiller 10y agoYes, 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.
- frant-hartm 10y agoI guess every generation of developers has to do its own mistakes.. http://www.omg.org/spec/CORBA/ http://www.omg.org/spec/CORBA/ https://www.w3.org/TR/2007/REC-soap12-part0-20070427/ https://www.w3.org/TR/2007/REC-soap12-part0-20070427/
- coldtea 10y agoThat might be true, and happens in lots of areas, but Swagger is nothing like Corba/SOAP specs and JSON is nothing like SOAP. JSON gives most of the stuff SOAP was actually used for (except for bureaucratic spec-driven edge cases), for 20% of the complexity -- so the JSON generation did something right. (I'm old enough to have been through CORBA and SOAP).
- TeMPOraL 10y ago> so the JSON generation did something right Rediscovered S-expressions and reimplemented them in a mix of square and curly braces ;).
- cookiecaper 10y agoYour post appears to characterize any such IDL as a "mistake". What makes attempts to formalize an API in this manner inherently problematic? Or did you just mean that it's a mistake to do a different IDL for REST-specific APIs instead of using an extant one? Does your complaint extend to non-web IDLs like Thrift or protobufs? In my experience, there is nothing inherently wrong with this type of IDL. Like all architectural decisions, it comes with its own tradeoffs, but there's no reason the tradeoff profile is inherently wrong.
- cocktailpeanuts 10y agoGoddammit why are they still calling it swagger (Pardon my french), i thought they came to senses and decided to use "OpenAPI"
- joshuata 10y agoJust read the first paragraph: "...Since then, it's been moved to the Linux foundation and renamed to Open API"
- darrelmiller 10y agoWe're not :-)
- kissgyorgy 10y ago"Over the past few years, Swagger 2 has become the de facto standard for defining your API." - LOL. I stopped reading here.
- edent 10y agoWhat do you use for defining & documenting your APIs? I ask because this is something the UK Government is looking at - https://github.com/alphagov/tech-and-data-standards/issues/31 https://github.com/alphagov/tech-and-data-standards/issues/3...
- zeptomu 10y agoI think most are crafted by hand. Maybe the problem is similar to language, compiler and interpreter design. There exists specific software that tries to help you with providing solutions for sub-problems (lexers and parser-generators), but they are hardly used, as they are hard to customize (see a recent discussion about writing a recursive descent parser), so people hand-craft them. When designing an API the hard part is getting it right(tm) and hopefully guarantee some kind of backwards compatibility and providing a clear path for its consumers, in particular documentation. It is possible to auto-generate some parts of the documentation, but such documentation is probably as helpful as auto-generated javadoc without notes provided by humans.
- bpicolo 10y agoThe best part about Swagger is there's a lot of good open-source tooling for it (though this depends on the language). One alternative I find super interesting lately is defining APIs with grpc and then exposing them with the gateway proxy: https://github.com/grpc-ecosystem/grpc-gateway https://github.com/grpc-ecosystem/grpc-gateway In this way, you get strongly-typed interfaces and Swagger is autogenned for you.
- pbreit 10y agohttp://readme.io http://readme.io
- abraae 10y ago
- tscherno 10y agoAfter writing a lot of long swagger specs I tried RAML which although not that widely supported feels much more pleasant to write. Any toughts?
- bpicolo 10y agoWrite swagger in yaml and it's just as pleasant.
- xiaoma 10y agoHow so? At least in my experience, Swagger doesn't have anything equivalent to traits so there's no way to DRY out your docs. If you have 50 endpoints with pagination, you have to document how that works 50 times. If you change how pagination queries are structured, then you have to change your docs in 50 places. With RAML, you would just change the trait and then all of your docs and your automated testing against them will be updated. Swagger does have $ref, but it's a much weaker abstraction than RAML traits and resourceTypes. http://raml.org/developers/raml-200-tutorial#traits http://raml.org/developers/raml-200-tutorial#traits
- pbowyer 10y agohttp://stoplight.io/ http://stoplight.io/ lets you use traits in Swagger. I've really enjoyed using a visual tool to build the API definition, though I don't find it helps with writing documentation.
- curun1r 10y agoAdd API Blueprint to the list of more pleasant to write alternatives. Not to mention it's much easier to render into human-readable documentation. I too have been somewhat dismayed by the rise in popularity of Swagger when there are two competing solutions that, to my mind, are superior.
- xiaoma 10y agoYes, RAML is great. I find it a lot more concise and don't see any advantage to using Swagger, despite that it's older and more widely used.
- davidbanham 10y agoWhat's the advantage of OpenAPI over json hyperschema?
- rpnzl 10y agoI'm also curious -- my guess would be the quality and availability of tooling depending on which snowball continues to grow. I only have experience with hyperschema (from an API design perspective). Would love to hear a current perspective from someone who had experience with both.
- jaequery 10y agoWow, I was expecting the price for a service like this to be around $20/month but $199/month (custom header/footer) for a service like this seems a bit of a stretch.
- gkoberger 10y ago$199 is just our most expensive plan! You should be able to do everything on the lower plans. And, we do much more than just host Swagger :)
- danielstocks 10y agoNo one using API blueprint here? https://apiblueprint.org https://apiblueprint.org
- wehadfun 10y agoHow does Swagger work with Odata and the Graph
- darrelmiller 10y agoWe 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.
- wehadfun 10y agoHow does Swagger work with Odata and the Graph
- kozikow 10y agoIs there a version of swagger-editor for OpenApi? I can't find anything. Similar experience for OpenApi would be a minimal requirement.
- k_sh 10y agoThe current Swagger-Editor supports Swagger 2.0 (aka OpenAPI Specification 2.0). OAS 3.0 will be supported some time after 3.0 is finalized. Source: I maintain Swagger-Editor. Check it out, we just finished a rewrite last week!
- bpicolo 10y agoCan swagger editor load and save with a file dialogue yet? I remember that being the most annoying missing detail when trying to use it.
- gkoberger 10y agoSwagger and OpenAPI are the same thing. They made a confusing name change somewhere between 2 and 3. (Swagger = trademark owned by SmartBear, OpenAPI = new name, run by Linux Foundation)
- darrelmiller 10y agoYou 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.
- lobster_johnson 10y agoI hope it's better than Swagger 2. I really need something like it, but trying to use Swagger -- after seeing that Kubernetes was using it -- has been a disappointing experience. I'm particularly frustrated with the lack of good documentation generators. That's more important, in my opinion, than using it to generate clients and servers.
- k_sh 10y agoI assume you've tried Swagger-UI[1] already? We just put out a new version (complete rewrite), you can see it in action here[2]. If you're not a fan, please feel free to open a ticket to give us some feedback. Disclosure: I was contracted to build Swagger-Editor 3.0. [1] https://github.com/swagger-api/swagger-ui https://github.com/swagger-api/swagger-ui [2] http://petstore.swagger.io/ http://petstore.swagger.io/
- lobster_johnson 10y agoYes, I'm familiar with it. And I'm sorry to say that I don't like it at all. Some things I dislike: * It's just a flat list of endpoints. You have to click on each to get a description, and it has this sluggish animation that opens up. I want to browse. * Way too much wasted screen real estate. The huge, wide table that shows when an endpoint is "open" is ridiculous. * For any given type, have to switch between "Example Value" and "Model", which is awkward. There's a missed opportunity there, too: Consider the "PUT /user/{username}". Why is the "type" of the body not User? Why couldn't it be a link to the model? I.e. "PUT" takes a User and returns a User. Swagger-UI uses so much empty space to represent this very simple protocol. * Whatever is being used to display the model is hard to use and read. You have to click on the little arrow to expand each level, and the font sizes are very inconsistent. etc. I do wish I had something vastly superior to give as an example, but I can find a lot of faults with every single API documentation site out there that I can think of. I do know some decent ones, though: https://stripe.com/docs/api/curl https://stripe.com/docs/api/curl https://www.twilio.com/docs/api/rest/sending-messages https://www.twilio.com/docs/api/rest/sending-messages https://plaid.com/docs/api/ https://plaid.com/docs/api/ This is the level of quality you at least have to reach before my interest is piqued. I like that these include runnable client examples in multiple languages, and includes more than just dry reference documentation; there are descriptions of actual semantics. Moreover, the documentation is presented in an organized way, by topic, and let's the user consume the information linearly without lots of clicks. As a simpler example, years ago a colleague of mine made a simple autogenerated documentation browser with built-in request running (screenshot [2]), which turned out pretty good. It's simple, but still miles ahead of Swagger-UI in terms of usability. I sometimes wish I'd spent some effort working it into something reusable. [1] https://stripe.com/docs/api/curl https://stripe.com/docs/api/curl [2] http://i.imgur.com/x5g1s2R.png http://i.imgur.com/x5g1s2R.png
- stephenr 10y agoWtf is "git flavored markdown"? Do you mean GitHub Flavoured Markdown? It concerns me that people writing software somehow mix up Git and GitHub as being the same thing.
- gkoberger 10y agoWhoops, fixed!
- willvarfar 10y agoGot all excited and awash with nostalgia when seeing the word "swagger" again. Clicked hoping it was about the old "swagger" Pascal snippet library that used to get passed on floppy disk in playgrounds in the 90s. Googling finds this: http://swag.delphidabbler.com/ http://swag.delphidabbler.com/
- tannhaeuser 10y agoSwagger, OpenAPI, RAML, JSON Hyperschemas, toml/yaml/json ... I don't see how proliferation of ad-hoc syntax contributes to interoperability, which surely should be the goal of an API spec? My take is that JSON has "won" over XML as RPC or REST serialization format because browsers support it OOTB and there's no schema needed. It simply is the way of least resistance. And since a browser front end is traditionally tied to a web backend anyway, there's no need for a formal "API" (protocol spec, actually) spec as an external artifact most of the time. Once you try and impose typing on JSON, this very benefit turns against you, and is getting absurd IMHO. Every JSON typing regime needs to work around the fact that JavaScript isn't statically typed. Consider JSON Schema: it is reminiscent of a markup schema of sorts, when a more rational approach would IMO be to represent JSON payloads as an RPC/IDL function signature-style schema.
- davidbiesack 10y agoThe example showing how response bodies are specified (media types, content) unfortunately is attached to a GET operation - please use a POST to demonstrate request bodies.