DEV Community

What API documentation generator/tool do you use?

Ari Kalfus on November 14, 2019

What API documentation generator / tool are you folks using? Hard requirement for me is version-able documentation - you can change versions on th...
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

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

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

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

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
 
obone profile image
O.B.One • Edited

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

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

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
 
sambhal profile image
Suhail Akhtar

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

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

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
 
iamdeveloper1107 profile image
iamdeveloper1107 • Edited

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

 
texas_kristen profile image
Kristen White

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.

Collapse
 
king11 profile image
Lakshya Singh

Redoc is also great for documentation.

Collapse
 
steelwolf180 profile image
Max Ong Zong Bao

I'm the person that would go for Postman as it's a one stop shop for my needs from designing to mocking and finally documentation.

Collapse
 
artis3n profile image
Ari Kalfus

😧

Oh no! Hopefully some of these resources people are posting can help.

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.