7 ms·

I think there's also a missing gap in how to present Swagger beautifully, the default one ( https://petstore.swagger.io/ https://petstore.swagger.io/ ) is meh.

I think there's also a missing gap in how to present Swagger beautifully, the default one ( https://petstore.swagger.io/ https://petstore.swagger.io/ ) is meh. I'm looking for something that can generate like https://stripe.com/docs/api 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

spondylosaurus 3y ago
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.
- starkparker 3y ago
  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 https://www.youtube.com/watch?v=0OKRNQvZbL4
  - spondylosaurus 3y ago
    Ooh, thanks for the link! WTD talks are always great.
mmcclure 3y ago
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 https://github.com/Redocly/redoc). When we redid the Mux docs (https://docs.mux.com/api-reference 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.
thecosas 3y ago
More here on the system Stripe uses for their docs: https://stripe.com/blog/markdoc https://stripe.com/blog/markdoc They open-sourced parts of it here: https://markdoc.dev/ https://markdoc.dev/ HN discussion here: https://news.ycombinator.com/item?id=32835751 https://news.ycombinator.com/item?id=32835751
- arek_nawo 3y ago
  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.
skimdesk 3y ago
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/ https://doctave.com/

spondylosaurus 3y ago

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.

starkparker 3y ago
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 https://www.youtube.com/watch?v=0OKRNQvZbL4
- spondylosaurus 3y ago
  Ooh, thanks for the link! WTD talks are always great.

mmcclure 3y ago

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 https://github.com/Redocly/redoc). When we redid the Mux docs (https://docs.mux.com/api-reference 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.

thecosas 3y ago

More here on the system Stripe uses for their docs: https://stripe.com/blog/markdoc https://stripe.com/blog/markdoc They open-sourced parts of it here: https://markdoc.dev/ https://markdoc.dev/ HN discussion here: https://news.ycombinator.com/item?id=32835751 https://news.ycombinator.com/item?id=32835751

arek_nawo 3y ago
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.

skimdesk 3y ago

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/ https://doctave.com/