What API documentation generator / tool are you folks using?
Hard requirement for me is version-able documentation - you can change versions on the documentation page in case you're not up-to-date and get whatever we've set as the documentation at that version. Ideally the documentation would show a pull request-like output (red deleted, green added) between versions as well. I remember there being a documentation generator that did this some years ago but cannot remember the name. Pretty sure the maintainers stopped working on it.
I am really trying to avoid Swagger/OpenAPISpec. I have not enjoyed using it in the past. Coming from a security background, Swagger's maintainers' misunderstanding of some pretty important concept like CORS bothers me in an irrational way. (Hint: CORS is not, as they claim, a security control; it is a security bypass).
I've heard good things about https://readme.com, however I do not like that there is not a single example of their product on their site. They make you contact them to register before - presumably - you get to see what their product actually looks like.
EDIT: The readme founder has helpfully commented below and explained that the company logos listed on the web page link to each company's respective public docs. They serve as good examples of the product.
https://readthedocs.org/ seems decent and has that versioning support I am interested in.
I could build a GitHub Learning Lab for my API... /s.
What do you folks use? If you use the OpenAPISpec, as I imagine most do, what tools do you use to generate your docs? Do you like what you use? What is it missing?
EDIT: Good folks in the comments have reminded me that ApiDoc is the documentation that I describe above and couldn't remember the name of. There are some really interesting new products in the comments; I am not sure which I will proceed with.
Latest comments (36)
We know that your tech team is busy building the product and its features. They might not have time for the documentation that explains how everything works, even though it’s important from the company’s point of view. This is where Perfect Documentation can help. We can assist you in preparing those documents so your team can stay focused on what they do best.
I'm not in the loop about the details of their deployment, but yes, they are still using Stoplight. I'm not quite sure what you mean by new version.
Redoc is also great for documentation.
Hey! Founder of ReadMe here! We do have a ton of examples (try clicking any of the logos), and you don't need to contact us to sign up... there's a signup link and a completely free trial with all the features enabled!
I didn't know the company logos were clickable. Those are great examples. Thanks!
I used SpringRestDocs (spring.io/projects/spring-restdocs) plus Asciidoctor and couldn't be more happy
You can write your documentation manually and include snippets generated from your test. You can assert the test to align the request/response with the documentation and fail if some of them is not what the documentation expects
You could try FastAPI: github.com/tiangolo/fastapi
You write your code in Python, using standard Python type declarations, and it generates OpenAPI for you, including Swagger UI and ReDoc.
I see you don't want OpenAPI, but it might be worth checking as it can help you simplify things. It also has OAuth2 integrations that can facilitate security.
Disclaimer: I'm the author 🤷
Hyde and Jekyll.
C++ documentation tool Hyde. Clang based using libTooling library. Produces structured markdown files, with YAML front-matter. And helps maintain the API documentation by mashing C++ changes with the documentation, so the documentation stays in sync with the evolving code.
Jekyll transforms markdown to static HTML, which can then be easily pushed en masse to your internal (intranet) or external (internet) webserver.
I've been working on an open source tool that's kind of like Git but for APIs. It that automatically writes and maintains your API spec to save time and ensure its accuracy useoptic.com
This looks really neat.
Re: your point on CORS, Smartbear (maker of the Swagger tools) are not the maintainers of the OpenAPI specification, and the official site / github repo don't contain such an article.
I'm using app.restcase.com
It's a great online utility for maintaining your API specifications.
It allows project level management of APIs, generate nice shareable UI specification for the APIs, and even provide tests infrastructure for the It's based on OpenAPI v2 and v3 so it's easy to migrate to it.
I'm using this tool to sync between QA and development department