DEV Community 👩‍💻👨‍💻

Ari Kalfus
Ari Kalfus

Posted on • Updated on

What API documentation generator/tool do you use?

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 (39)

Collapse
 
mitsik profile image
Evgeniy

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”

Collapse
 
artis3n profile image
Ari Kalfus

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.

Collapse
 
scottydocs profile image
James.Scott

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

Collapse
 
artis3n profile image
Ari Kalfus

Stoplight.io looks pretty interesting. Will check it out, thanks.

Collapse
 
texas_kristen profile image
Kristen White • Edited on

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/

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

Thread Thread
 
shakesbeardz profile image
Yahia Battach

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

Thread Thread
 
texas_kristen profile image
Kristen White

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.

Collapse
 
rhymes profile image
rhymes

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.

Collapse
 
artis3n profile image
Ari Kalfus • Edited on

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.

Collapse
 
acunniffe profile image
Aidan Cunniffe

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

Collapse
 
artis3n profile image
Ari Kalfus

This looks really neat.

Collapse
 
tiangolo profile image
Sebastián Ramírez

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 🤷

Collapse
 
jon0231 profile image
jon0231

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 !

Collapse
 
artis3n profile image
Ari Kalfus

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.

Collapse
 
artis3n profile image
Ari Kalfus • Edited on

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.

Thread Thread
 
jon0231 profile image
jon0231 • Edited on

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

Collapse
 
eljayadobe profile image
Eljay-Adobe

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.

Collapse
 
obone profile image
O.B.One • Edited on

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

Collapse
 
gkoberger profile image
Gregory Koberger

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!

Collapse
 
artis3n profile image
Ari Kalfus

I didn't know the company logos were clickable. Those are great examples. Thanks!

Collapse
 
singh1114 profile image
Ranvir Singh

I haven't personally used it. But I have seen a lot of people use it.

github.com/slatedocs/slate

Collapse
 
artis3n profile image
Ari Kalfus

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.

Collapse
 
shalvah profile image
Shalvah • Edited on

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.

Collapse
 
lloricode profile image
Lloric Mayuga Garcia
Collapse
 
artis3n profile image
Ari Kalfus

apiDoc is the generator I couldn't recall the name of! I really enjoyed using this in the past.

Collapse
 
jagedn profile image
Jorge Eψ=Ĥψ

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

Collapse
 
mateuszjarzyna profile image
Mateusz Jarzyna

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

Collapse
 
artis3n profile image
Ari Kalfus • Edited on

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?

Collapse
 
sambhal profile image
Suhail Akhtar

I have started using npmjs.com/package/swagger-jsdoc

Collapse
 
mikeralphson profile image
Mike Ralphson

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.

Here is a post you might want to check out:

Regex for lazy developers

regex for lazy devs

Sorry for the callout 😆