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