Ask HN: What are you using to create API documentation in 2022?

by waitlist on 10/25/2022, 1:02:08 AM with 4 comments
I have a small indie software business, and an important part of my product is that it can be integrated by API.

Today, I'm using Stoplight to host my API docs (https://waitlist.stoplight.io/docs/waitlist-api-no-auth). I like Stoplight -- it allows me to write example calls that users can copy-paste, has schema definitions so it's easy to document REST, and well-designed features for documenting all the details (endpoints and their HTTP verbs, headers, HTTP responses, etc.).

However, Stoplight is expensive -- $99/mo.

I'm looking at alternatives, but I'm not finding anything good:

* Docusaurus is a good markdown static site generator, but is totally lacking for details: no ability to re-use schemas, create example calls, etc.

* Documentator is defunct.

* Readthedocs requires significant overhead in form of a Sphinx integration and self-rendering

* Readme.com has similarly expensive pricing to Stoplight and a worse UX (in my opinion)

What are you using? I'd love to be able to rely on a simple managed service that doesn't break the bank.

  • by ndimares on 10/25/2022, 8:35:42 AM

    Hi I'm actually working on a guide for this exact topic. My basic thoughts are that there's currently no magic bullet solution and it depends primarily on your technical ability and resourcing:

    -0 technical skills: notion or atlassian -pseudotechnical (github & markdown skill): gitbook, or readme -technical with resourcing constraints: docusaurus, or hugo or mkDocs. -technical w/o constraints: custom react site: Markdoc + Next.js or Gatsby

    The company I'm at is currently technical w/ constraints. We use docusaurus and we use a plugin for autogenerating the openapi documentation: https://github.com/PaloAltoNetworks/docusaurus-openapi-docs

    It works. The results are not spectacular, merely passable. We think in the near future we will build our own plugin for the community. If you ever want to char docs, get in touch!

  • by slorber on 10/25/2022, 9:35:13 AM

    Docusaurus maintainer here. I don't really understand what you mean, considering we don't have official support for API documentation, but have a plugin system allowing you to build your own support.

    And we have a few OpenAPI plugins, and redocusaurus.

    A Docusaurus plugin MDX makes it possible to implement this with client-side React in case you want to create an interactive client alongside editorial text content.

    See what Courier did just using React in MDX, and without any Docusaurus plugin: https://www.courier.com/blog/how-we-built-our-documentation/ https://www.courier.com/docs/reference/send/message/ (their site is opensource)

  • by docmechanic on 10/25/2022, 1:23:06 AM

    Hugo has an active ecosystem and good documentation: https://gohugo.io/