Is OpenAPI Documentation Superior?

Question

We've been using SlateDocs over at https://butterflylabs.gitlab.io/api-documentation for our documentation. However anytime we see docs, people mention OpenAPI solutions. Outside of the autogenerating aspects, are there benefits for the API consumer?

mooreds · Accepted Answer

I've been looking at this (we have a lot of docs and our API docs are all written in asciidoc). I don't think the value of OpenAPI is in the documentation, though it seems pretty thorough.

There are a lot of benefits for the API producer in terms of tooling and the ecosystem.

But that tooling also helps the consumer. Look at all the tools listed here: https://openapi.tools/ Those that would be helpful to me as a consumer of an API are:

   * Documentation
   * Learning
   * Mock servers (for testing)
   * Some of the tools under misc
   * SDK Generators. Most people don't want to consume an API using REST, they want to use their fav language to do so

I asked in a slack full of developer relations folks about alternatives to OpenAPI for defining REST APIs and didn't hear any good alternatives.

SlateDocs looks really nice, though. As sibling comments have pointed out, you can have both.

bigiain · Answer

> Outside of the autogenerating aspects, are there benefits for the API consumer?
Mostly familiarity.
The OpenAPI spec and the Swagger tools are something that a _lot_ of devs are familiar with, and they integrate well with lots of other tools (We have OpenAPI docs embedded in out Confluence/Jira workflow).
That SlateDocs looks nice, but I've never heard of it before.
If I had two browser tabs open to evaluate different 3rd party APIs to consume, I'd somewhat strongly lean towards the one that used OpenAPI, because I know it'd fit in with our existing toolset and experience.

margor · Answer

There is also https://apiblueprint.org/ that I really enjoyed working with even by hand writing the underlying specs and using their proposed docs generators. But it was almost 2 years ago so not sure what is the state of it now.

tdeck · Answer

I'd say the answer is no. People use OpenAPI because it produces a good result and fits conveniently into a company's workflow.
The most important aspects of good API documentation are
1) correctness,
2) thoughtful and complete examples, and
3) a clear explanation of the data model and state transitions.
These can be accomplished with any tool.

Meic · Answer

You can do both. Widdershins converts an OpenAPI definition to the markdown format used by Slatedocs. https://github.com/mermade/Widdershins

tobilg · Answer

You might also look at https://github.com/tobilg/api2html