Basically, see the title.

I have good reasons. Small example:

Recently, I worked with a partner's team on one project's API documentation, and with a contractor on completely different project, and its API docs. Different companies, even.

The Partner Team at one company uses Swagger. The Contractor wants to use the Postman API Documentation Tool. Meanwhile, I don't use either.

I use Emacs. I need no other tool for these things.

As I describe elsewhere in this blog, to generate API documentation after making changes in my literate API org file, I type C-c C-e h h. That's it. Dude clicks a button. Other dude clicks a button. I type that mess. Which is harder?

After I type C-c C-e h h, unlike dudes clicking buttons, I have to wait a bit as Emacs makes innumerable actual API requests to get data to fill out the "Response" section in the API docs. I don't get an instantaneous response, because unlike other solutions, this isn't a toy.

It took skill to write. The same skill on display in the API, itself.

I usually watch as Emacs builds my static API documentation, replete with JS, because as soon as I see unusual errors popping up, I know something is wrong. I can hit C-g and switch to the *Messages* buffer to find out how the API responded. What the error was, and maybe how to fix it.

Then I can run again. C-c C-e h h.

I still have not left Emacs.

Swagger:

Compare to Swagger. I spent a day and part of a night writing yaml that does nothing. It does not make any API requests. It does not let me make SQL requests, or use bash or python or R or restclient. It just makes cookie-cutter API documentation with extremely limited "documentation" because you basically have to document in yaml or json.

The real issue with Swagger is that it's a toy. It's buttons with rudimentary documentation, and an ecosystem that encourages code-generation. Sorry, but no. I like writing code. I don't want to spend days learning and setting up a configuration-first system where I don't have to write code.

I did the work to make some Swagger, because it was required. But while I did it, I also wrote an org file that actually calls each endpoint, and shows me the response and response headers, in full. In Emacs. In the file, under version control. As an afterthought, I added a link to the Swagger file as a link when the API documentation exports.

Postman API Documentation Tool:

Recently, a contractor wanted to update the API documentation on the project we're working on together, and he was confused. He immediately concluded that I was manually updating the API documentation, and suggested something that everyone could use, like Postman.

I sent him a link to Orgdown. I'm sorry, but why should I learn Postman – a proprietary commercial product – instead of him learning Orgdown? He doesn't have to install anything. I have to install Postman, get an account, share that account with him… so much STUFF for something I will only use because of him. The other back-end engineer already groks org.

It got me to thinking, though. Why not switch to Postman? He has a point. I'm an Emacs evangelist… definitely a fringe group. I'm also not a snob. VS Code is fantastic. Vim does stuff. I know :qw so… Why not embrace some API documentation framework?

Conclusion:

No. I will continue to use the README.org that magically turns into a beautiful, up-to-date API doc with four key-chords. That makes SQL queries to my dev DB to find out which records to use in queries. That uses free bash tools like jq to compose data for display.

I want to keep my API documentation under version control with the API code. So, if I roll back… bye-bye documented changes. I want my API to be in perfect sync with the documentation. I want it to be programmatic. I want it to actually make an HTTP request with a valid bearer token to a real endpoint, get a response, and include that response in pretty HTML. I want it all.

I don't want a demo, like Swagger. I'm not writing a business plan. I'm writing documentation for something that already exists. I don't want to yaml that describes the structure of example responses and maintain them when they change.

And I don't want to login to an app and click buttons. My RSI is bad enough as it is, and it's all mouse (my left pinky is just fine, thank you). When I want to know what's in an S3 bucket, do I browse to the AWS console? No. I use awscli. It's under my fingers, already. When I want to test my new API endpoint while I'm working on it, do I make a new request in a collection of Postman, which is completely useless anywhere else? No. I create a restclient source block and hit C-c C-c. That simple.

Yes, I know how to use Emacs.

No, I do not know how to use Postman.

Yes, I'm the Software Architect.

Guess which way we're generating API docs?