redoc

OpenAPI is great, we use it in combination with redoc (https://github.com/Redocly/redoc) to have a almost 0 effort API for our product. But man, my tokenizer is in trouble with OpenAPI and OpenAI.

There are a few other tools out there that are at least marginally better than the default Swagger UI such as ReDoc (https://github.com/Redocly/redoc). When we redid the Mux docs (https://docs.mux.com/api-reference) we actually just decided to build our own renderer. It really wasn't as bad as you might think, at build time we pull in the JSON version of our OAS spec and render it as a static build in our Nextjs app. Don't get me wrong, it wasn't trivial, but the benefit of having complete control over the output has been well worth it.

Did you try https://github.com/Redocly/redoc ?

Also an Atlassian here. For anyone wondering, we tend to use Confluence for planning, decisions, team process, tech specs, etc but use an internal view of DAC[0] for code docs. Think Hugo[1] crossed with redoc[2] with a dash of GraphQL support. Unfortunately the docs-in-repo + PRs-for-updates approach has way more friction for drive-by-corrections/commentary/Q&A from people not on the team, so it's not a holy grail either. [0]: https://developer.atlassian.com/cloud/ [1]: https://gohugo.io [2]: https://github.com/Redocly/redoc

The best CLI documentation generator I've found so far is Redoc[1]. There are tons of hosted solutions for docs (Apimatic, SwaggerHub, Stoplight, and Apicurio Studio). My favorites are SwaggerHub[2] and Apicurio[3], because their editors are solid and they have good compatibility with all the nooks and crannies of the OpenAPI v3 spec. 1. https://github.com/Redocly/redoc 2. https://swagger.io/tools/swaggerhub 3. https://studio.apicur.io

I've seen Slate. I know CircleCI uses them. Personally however I am a huge fan of redoc. Something about the way redoc looks and the way it is served makes me want to pick them over slate. https://github.com/Redocly/redoc I've managed to get both the companies I work at use redoc instead of slate :)

Indeed, it sounds like there was a bit of a problem "between keyboard and chair" when it came to the Postman / Paw user with whom you interacted. I had good success, just recently, using Paw to knock out the broad strokes an OpenAPI description, including indications of integer, string, boolean, date, etc. After I got the hang of thinking in terms of OpenAPI, I converted the JSON to YAML and started fine-tuning and DRY'ing the description in Emacs. I would still use Paw as an exploratory tool — it's not perfect, but I find it more convenient than maintaining a collection of scripts and snippets to experiment with API input/output. Next time I need to write an OpenAPI description, though, if I can't auto-generate it from the server code (that was the case recently), I'll just author it by hand. It's not too big of a chore when done in YAML

I was recently tasked with tightening up and documenting an HTTP API I didn't write. The original authors used Django and Django REST Framework[1], but lacking deep experience with either, mostly rolled their own functions for requests, responses, and communications with the back-end databases and other external data sources. Rather than attempting to sort it out, I used Paw[2] to get my arms around the API from a consumer's POV, had Paw generate a skeleton of an OpenAPI 2.0 (Swagger 2.0)[3] description, converted it to YAML[4] and began putting flesh on the bones manually (yaml-mode[5] in Emacs is pretty decent). In the process of covering all the bases with precise req/res definitions and examples (yay, JSON Schema![6]), I uncovered a lot of corner cases in the API's functionality and made sure they were handled properly or at least doc

Scroll down, https://github.com/Rebilly/ReDoc

Looks like the site was generated by this [0]. They'd probably appreciate someone raising an issue. [0] https://github.com/Rebilly/ReDoc

ReDoc looks pretty good - https://github.com/Rebilly/ReDoc I particularly like its approach to presenting hierarchical data structures.

HMAC for auth to avoid having the key exposed at every request. For the rest: http://www.javabeat.net/rest-api-best-practices/ And documentation: https://github.com/Rebilly/ReDoc/blob/master/README.md There many more comprehensive resources about sane API design (use HATEOAS, pagination, etc.) but you don't have to implement everything from v1 ps. SSL goes without saying even if it's a public API

For Web APIs OpenAPI Specification has been a great resource for internal and external projects. With viewers like https://github.com/Rebilly/ReDoc/ it gets pretty easy to take the spec and generate something pleasing for a consuming developer. Unless you are talking about native code APIs ...