
The Open API Initiative - xrorre
https://openapis.org/
======
whatnotests
What most API documentation lacks is one thing.

Examples.

Real, working, copy-n-paste examples.

While I prefer the swagger format, we use Blueprint at work because it's
trivial to include an actual example request or response as part of the
documentation.

Sure, schema helps, but having a spot to just lay out an example request or
response is really important.

Another thing: often, one must perform prerequisite steps before making a call
to a given API method. Eg - you must have booked a flight before checking in.
The context surrounding how an API fits into its use-cases is as important as
the API itself.

~~~
porpoisemonkey
There does appear to be an examples section in the project repository

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

~~~
palakchokshi
I believe he meant a way to put examples in the spec itself. I believe they
have a client SDK that will consume the API spec and allow you to make
requests and see responses.

~~~
porpoisemonkey
Ah I see. The OpenAPI specification for the interface description language and
the auto-generation tools are actually two separate entities so I'm not sure
it would make sense that they put examples for a specific auto-generation tool
in the official OpenAPI repository.

It seems like the best supported tool for generating client and server stubs
is Swagger Codegen. Version 2.1.2 seems to support the OpenAPI 2.0 draft spec.

[http://swagger.io/swagger-codegen/](http://swagger.io/swagger-codegen/)

[http://swagger.io/getting-started/](http://swagger.io/getting-started/)

------
palakchokshi
Next will come the API spec parsers to automate client code generation. Those
will break on the first vendor specific extension. Vendors will put in
extensions for security, pre and post request action guidance, etc. This will
cause vendor specific client code generators to be created. The specification
will take a long time to get updated as each vendor will want their extensions
in the core specification. As a result even more extensions will be created.

We have seen this cycle before with WSDL and XML Schema, etc. I hope we have
learned from our mistakes and don't go down the same path to have history
repeat itself.

Personally I like the idea of an API Specification but the practical use has
been a let down so far.

~~~
doublerebel
Auto-generated client side consumers for APIs already exist, and are quite
useful: [https://apimatic.io](https://apimatic.io) .

If we can get producers to standardize all or part of their API, then we gain
the ability to switch easily between providers and force them to compete on
service instead of proprietary lock-in.

Ideally.

------
Oras
In this page: [https://github.com/OAI/OpenAPI-
Specification/tree/OpenAPI.ne...](https://github.com/OAI/OpenAPI-
Specification/tree/OpenAPI.next) The link to current specification is broken

Review the [current specification]. The human-readable markdown file is the
source of truth for the specification.

~~~
porpoisemonkey
Noticed the same thing. After some digging I found what appears to be the
latest draft spec here: [https://github.com/OAI/OpenAPI-
Specification/blob/master/ver...](https://github.com/OAI/OpenAPI-
Specification/blob/master/versions/2.0.md)

------
yeukhon
The real major Open API I always think is required is an Open API allow me to
interact with any part of a website so people can finally build assistive
technology based on API rather than parsing some website's DOM that you will
likely never be able to parse out correctly from version to version. If the
website exposes a "REST" specification how to interact with the pages, then we
can really build a website visual impaired can finally used. Just my rant
after trying to build one and realized how crazy it was to learn to work with
DOM.

~~~
palakchokshi
What you are looking for is the semantic web or an accessible web. There are
standards to create an accessible website but few developers do it unless
their market has a significant number of visually impaired people. This is
further complicated by Single Page Applications and/or web apps. If there was
a browser extension or something that made every website accessible that would
be an awesome extension.

------
malandrew
Too little, too late.

Thrift, gRPC, YaRPC, etc. are all RPC frameworks with strong typing and binary
transports. They are still immature, but as such frameworks mature and support
more languages, they will eat the lunch of any project trying to build on
REST.

------
JimDabell
Does anybody have any recommendations for a Swagger-style documentation
toolchain for REST APIs? I mean actual REST, not this weird anti-REST where
you predefine fixed URI structures up front.

REST APIs are based around media types, not URI structures. Unfortunately,
tools like Swagger are based around URI structures, which shouldn't be in REST
API documentation at all. It makes trying to find good tooling for REST APIs
difficult when people say "just use Swagger" and similar.

------
sharemywin
Is there a directory of apis that conform to the spec?

~~~
bbrennan
Yes! Over 200 specs are provided for free by APIs.guru:

[https://github.com/apis-guru/api-models](https://github.com/apis-guru/api-
models)

------
gtirloni
How's this related to WSDL?

