
Introducing the Open API Initiative - tangled
http://swagger.io/introducing-the-open-api-initiative/
======
Randgalt
Do API docs actually provide much benefit in practice? Does anyone actually
use Javadocs, for example? The problem with documentation at this level is
that it's too low level. It useful, maybe, as a quick reference once you
already know the project.

------
joshdotsmith
How does this compare to JSON API? [http://jsonapi.org/](http://jsonapi.org/)

Is this a competing standard? I'm getting fairly nervous about the rise of
competing "standards" with APIs.

~~~
wise_young_man
I'm less familiar with JSON API, but at first glance it looks like a standard
around JSON response bodies for APIs.

Swagger's standard API definition is external of your actual API responses and
is used primarily for API docs and can be used for auto generating API client
libraries/SDKs.

Here's an example:

[https://github.com/OAI/OpenAPI-
Specification/blob/master/exa...](https://github.com/OAI/OpenAPI-
Specification/blob/master/examples/v2.0/json/petstore.json)

------
autotune
Relevant XKCD: [https://xkcd.com/927/](https://xkcd.com/927/)

~~~
msoad
Except this is not a new standard. OAI is swagger, converted into a more open
standard than before.

