
A Visual Guide to What's New in Swagger 3.0 - gkoberger
https://blog.readme.io/an-example-filled-guide-to-swagger-3-2/
======
gkoberger
(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
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
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
It's worth adding that Swagger 2.0 documents will be losslessly convertible to
OAS 3.0.

------
frant-hartm
I 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/)

~~~
darrelmiller
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.

~~~
MichaelGG
There's nothing wrong with just "tunneling" SOAP or anything else over HTTP
POST. Tons of APIs do this and work just fine.

Now maybe it's easier on clients when you can just curl -XDELETE something but
I'm not sure it's that big of a difference in the end. Especially if you have
auto-gen'd client code.

~~~
darrelmiller
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.

~~~
MichaelGG
HTTP caching is a good benefit. But you can get it just by using GET and
shoving the body in the querystring.

Headers: Use the SOAP ones, you're just tunneling SOAP messages.

Idempotentcy requires the app to implement it that way. HTTP doesn't really
help there.

------
Dunedan
> 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
Total 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_arc...](https://www.ics.uci.edu/~fielding/pubs/dissertation/rest_arch_style.htm)
[2]
[https://tools.ietf.org/html/rfc7231#section-4.3.1](https://tools.ietf.org/html/rfc7231#section-4.3.1)

~~~
johnhenry
I tend to agree with the interpretation given here:
[http://stackoverflow.com/questions/978061/http-get-with-
requ...](http://stackoverflow.com/questions/978061/http-get-with-request-body)
\-- that if a GET request contains a body, the server should ignore it in
order to stay compliant with the spec.

------
kissgyorgy
"Over the past few years, Swagger 2 has become the de facto standard for
defining your API." \- LOL. I stopped reading here.

~~~
edent
What 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/3...](https://github.com/alphagov/tech-and-data-
standards/issues/31)

~~~
bpicolo
The 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.

------
stephenr
Wtf 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
Whoops, fixed!

------
tscherno
After 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
Write swagger in yaml and it's just as pleasant.

~~~
xiaoma
How 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
[http://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.

------
cocktailpeanuts
Goddammit why are they still calling it swagger (Pardon my french), i thought
they came to senses and decided to use "OpenAPI"

~~~
joshuata
Just read the first paragraph: "...Since then, it's been moved to the Linux
foundation and renamed to Open API"

------
willvarfar
Got 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
Swagger, 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.

------
gnidan
Is there any plan to expand the support for runtime polymorphism in 3.0?

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

------
lobster_johnson
I 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
I 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
Yes, 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)

------
jaequery
Wow, 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
$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 :)

------
davidbiesack
The 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.

------
davidbanham
What's the advantage of OpenAPI over json hyperschema?

~~~
rpnzl
I'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.

------
kozikow
Is there a version of swagger-editor for OpenApi? I can't find anything.
Similar experience for OpenApi would be a minimal requirement.

~~~
k_sh
The 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
Can swagger editor load and save with a file dialogue yet? I remember that
being the most annoying missing detail when trying to use it.

------
danielstocks
No one using API blueprint here?
[https://apiblueprint.org](https://apiblueprint.org)

------
wehadfun
How does Swagger work with Odata and the Graph

~~~
darrelmiller
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.

