loading...

What API documentation generator/tool do you use?

artis3n profile image Ari Kalfus Updated on ・2 min read

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.

Discussion

pic
Editor guide
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 Author

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 Author

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

Collapse
texas_kristen profile image
Kristen White

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.

Thread Thread
perryloh profile image
Perry Loh

Kristen - is that new version of developer.bigcommerce.com still using Stoplight? Ie. as a customised/self-hosted enterprise version of Stoplight.

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

Thread Thread
perryloh profile image
Perry Loh

I mentioned new version because there was a bigcommerce.stoplight.io and just assuming that was what you pointed out as 'legacy'. I was looking at developer.bigcommerce.com and saw there were hints of stoplight in there but couldn't confirm. I was wondering if they were using a self-hosted enterprise and customizable version of Stoplight then ?
ps. full disclosure, we are a new customer on Stoplight.io, and the level of customization we have available is obviously closer to bigcommerce.stoplight.io than developer.bigcommerce.com

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 Author

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 Author

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 Author

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 Author

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

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

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 Author

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 Author

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

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
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
lloricode profile image
Collapse
artis3n profile image
Ari Kalfus Author

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

Collapse
mkimont profile image
Matt Kimek

If we talking about web dev apps I will suggest to write it from scratch using curl and add validation layer in json (as business requirements).
You will have live documentation (live example + live validation)

The biggest issue with all of those 'frameworks' listed in comments are lack of live response/request (if I am not wrong). You can have documentation based on comments however if comments are wrong, your docs are wrong.

if I am not wrong - I hope that something like that exist now

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 Author

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
sambhalgithub profile image
Collapse
iamdeveloper1107 profile image
iamdeveloper1107

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

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 Author

😧

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.