Item — HN Reader

I think there's also a missing gap in how to present Swagger beautifully, the default one ( https://petstore.swagger.io/ ) is meh. I'm looking for something that can generate like https://stripe.com/docs/api but open source (since the OP is talking about it).

I imagine a tool(chain) that can take Swagger generated from annotations in code, and combine it with a folder containing Markdown files for "free form" documentation, and generate a Hugo/Jekyll static site that can be deployed in Cloudflare Pages in docs.mycompany.com

4 comments

More here on the system Stripe uses for their docs: https://stripe.com/blog/markdoc

They open-sourced parts of it here: https://markdoc.dev/

HN discussion here: https://news.ycombinator.com/item?id=32835751

This looks really interesting.

I was looking into implementing custom and conditional content blocks in Vrite editor but wasn't sure about the output format. MarkDoc seems like a great, standardized extension of Markdown that would be perfect for this use-case.

Will try to work on that.

FWIW, Stripe's API docs use a bespoke toolchain that (as I heard it estimated) cost $1mil+ to build. There's a good reason Stripe is the gold standard of API reference—they invest heavily in their documentation.

Considering how few other companies are willing to toss more than a few bucks at technical writers and tools, the difference is pretty stark.

Ryan Young, a tech writer at Stripe, gave a good talk at this year's Write The Docs on some of the philosophical choices they made in structuring their docs and responding to user feedback about where it didn't land as well: https://www.youtube.com/watch?v=0OKRNQvZbL4

Ooh, thanks for the link! WTD talks are always great.

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.

Combining Swagger (OpenAPI) with Markdown prose was what prompted us to build Doctave [0]. Jekyll does a good job, but breaks down once you need more bells and whistles, such as search and versioning.

It's early, but worth checking out.

[0]: https://doctave.com/