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.
Top comments (35)
Just yesterday I have setup Postman workspace for my api and it generated a pretty docs. Workspace supports collections just name your collection of requests as v1, v2 etc and you will get documentation for each βversionβ
I'm a big fan of having a Postman collection of your API endpoints, for your QA or pentesting teams. I didn't know they generated documentation, I will look into that. Also a good opportunity to compare to Postwoman.
I liked Slate but have also toyed around with Stoplight.io a bit. Worth having a look.
You can generate some fairly decent API docs with Postman too. You can't do a huge amount of customisation currently but this looks like it's a mid-term goal on their roadmap: trello.com/b/4N7PnHAz/postman-road...
Stoplight.io looks pretty interesting. Will check it out, thanks.
Full discloser - I work for Stoplight. I'm typically a docs consumer, not creator, so I don't have any real preference for how they're generated. All the same, as an employee I'm biased.
We've got 2 different docs options, this one is free & basic stoplight.io/docs/
If you need more theming options, this one is paid but there is a free trial stoplight.io/hubs/. Big Commerce uses this plan and they've made some pretty slick lookin' docs if I do say so myself. developer.bigcommerce.com/
I like the idea of the files changed red/green view, if that isn't a capability we already have, I'm going to add it to our roadmap (anyone can add & vote for roadmap items, it's found at stoplight.io/p/roadmap.)
Update We do have versioning capabilities on our docs hubs product stoplight.io/hubs/ docs.stoplight.io/platform/version...
thanks for the comment, I liked what bigcommerce did with stoplight.io but I wanted to try it in stoplight.io/hubs/ but I couldn't I think you are still working on it
Yeah, the version that BigCommerce started using a few years back is considered legacy now, we're rolling out the latest and greatest in mid-April. In the meantime, you can still write basic docs with stoplight.io/docs/ and the April release will include a bunch of neat features.
We use Redoc here at DEV, it generates from OpenAPI 3
I agree with you, that page is really troublesome, but we don't generate the API from the spec and we don't plan to. It's just used as a specification format.
Yeah OpenAPI is great for its ubiquity and cross-tool support, I have to admit. I like how Redoc organizes the content and its UI is clean.
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.
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 π€·
I use ApiDoc for my NodeJS - Express API, Generate an index.html with a little function, a simple npm to install, they have a good doc.
You just need to implement some commentary and Voila, you have your doc !
Ah, apiDoc is what I remember using a few years ago. I was really happy with it. Definitely going to compare it to some other options. It's got the versioning and just looks a little cleaner than readthedocs, which is nice.
Can you set up example requests with apiDoc? A quick look over its documentation doesn't seem to highlight this as a feature. So beyond documenting the API call in comments over the function, including an example request with request parameters filled out with some test data.
Sure, you to give you an idea, you have an "template" block i use and replace to edit my parameter, result and error :
And it give you that
thepracticaldev.s3.amazonaws.com/i...
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
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.
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!
we use this github.com/apidoc/apidoc
apiDoc is the generator I couldn't recall the name of! I really enjoyed using this in the past.
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
I haven't personally used it. But I have seen a lot of people use it.
github.com/slatedocs/slate
I like that this is markdown-based, although having to document the API separately from the code creating the API endpoints could lead to unintentional drift. I'm going to keep this one in mind.
If you're still looking, how about Scribe (I'm the maintainer)? It tries to extract the docs from your code with as little config as possible, and it can automatically call your endpoints to generate sample responses. We've got versions for Laravel and popular Node frameworks.
I have started using npmjs.com/package/swagger-jsdoc
I;m using ascii doc. You can generate doc during compile time, so there is a way to paste some code or http requests from tests
Asciidoc I'm really not excited about. You have to write out verbose stuff separate from your code and, in my opinion, it doesn't end up reading very easily. For API documentation - there are other documentation needs that asciidoc services. What are the reasons you use asciidoc?
I'm using Swagger UI to auto-generate API from Rest Controller, when we start API, we have Documentation :D...but It's so bad :( And I'm trying to change to another better than