Ask HN: Is OpenAPI Documentation Superior?

[hirokib]

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]

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.

[rocketpastsix]

as one of the maintainers of openapi.tools, thanks for the shout out! if we can do anything to make the little site better let me know and ill see about getting it done.

[hirokib]

ah so it's just as much about the discoverability. That's really cool!

[mooreds]

Thank you for all the work you're doing!

[bigiain]

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

[hirokib]

So there is an intuitive aspect that brings comfort? I think that's super important. Especially in healthcare where most APIs/dev experience is terrible, making someone feel at home seems really important.

[bigiain]

Not so much “intuitive“, much closer to “familiar”. I don’t expect an API doc tool (or any useful/powerful dev tool) to be zero learning curve, but I don’t want my team climbing 2 or 3 different learning curves unnecessarily.

But yeah, totally right on the “feeling at home” idea.

[margor]

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]

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.

[hirokib]

Fair enough. In regards to point number 3, do you believe that sandbox APIs that persist objects like what Stripe does a must-have or a nice-to-have or somewhere in between?

[tdeck]

For me it depends on what the API does, and how much testing costs.

If it's something like Stripe (payments), Plaid (collects bank credentials), or Lob (sends physical mail), you definitely need a sandbox beyond the MVP stage. At one point we had a pre-launch payments API at Square and we provided partners with prepaid debit cards to test with, but that approach obviously doesn't scale well.

Another huge benefit of sandbox APIs is that people can use them for CI when testing their own integrations.

Still, when the cost of creating and manipulating objects in the production API is negligible I would say a sandbox is unnecessary.

As for how much persistence is needed in the sandbox, start with what is easiest to implement and gather feedback from your developers.

Be aware that developers often throw out ideas of API features that would be nice to have without much though about priority of effort involved. Sometimes they ask for something and then don't get around to updating their integration to take advantage of it.

[hirokib]

ya that's a fair point. Right now we just give canned responses but our API does have real world implications like Lob. Actual test kits get sent out. It's hard to balance essentially duplicating your prod environment for the sake of simulating things vs canned responses which just give you the different responses you'd expect. I guess the big downside is you don't get to test asynchronous changes to objects.

[Meic]

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

[bigiain]

Oooh, nice. That looks potentially useful.

For people who haven’t clicked the link, this assumes you’re defining your API in OpenAPI/Swagger/a few other options, and (one directionally) converts it to suitable formats for static publishing:

Widdershins is generally used as a stage in an API documentation pipeline. The pipeline begins with an API definition in OpenAPI 3.x, OpenAPI 2.0 (fka Swagger), API Blueprint, AsyncAPI or Semoasa format. Widdershins converts this description into markdown suitable for use by a renderer, such as Slate, ReSlate, Shins (deprecated) or html suitable for use with ReSpec.

[gwittel]

Widdershins works pretty well. IIRC their README also links to a CLI tool that wraps Widdershins.

I containerized it and added some wrapper scripts so we can just drop the YAML spec in our repo and have build automation to generate/deploy a web site with all the relevant docs.

[hirokib]

I saw this and I'm definitely leaning towards it now given what was said in this thread. Thanks!

[tobilg]

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

[hirokib]

Sure. I'll check it out. I saw a similar product that would output OpenAPI to slate docs actually so that would be what I would lean towards just out of familiarity.