API documentation is one of those things that are important in a backend-frontend dynamic that no one really wants to do. Mostly because it's time-consuming and repetitive.

The tool I'll be describing is mitmproxy2swagger so if you want to cut to the chase, just scroll past these two paragraphs.

API documentation is a collection of references, tutorials, documents, or videos that help developers use your API governed by the Open API Specification(OAS). An API(Application programming interface) is a data-sharing technique that helps applications communicate with each other. Not the best definition in the world but I like to think of an API as a dynamic messenger. They can store your message, process it, and also deliver it to multiple people. They are also responsible for the security of your message until it reaches you.

There are a lot of tools in the market used to produce great documentation; Swagger, Postman, Doxygen, ApiDoc, and Document360 just to name a few. However, most developers remain oblivious to the tools developed for reconnaissance which when you interact with them are useful to developers as well.

mitmproxy2swagger

Imagine if you could reverse-engineer your API to generate documentation in 2 minutes. That would be perfect for quick documentation bridging the gap between backend and frontend teams just before you can get a longer-lasting solution.
MITM(Man in the Middle) - a term referring to a cyber attack where a malicious actor intercepts the communication of two parties without their knowledge. Being in the middle they can modify the data shared before they reach the recipient however they want.

Proxy - This is a server that acts as an intermediary between a client and a server. For context, the reason you can access the internet is because of a forward proxy that stands between you(the client) and the server that you're trying to access.

mitmproxy2swagger helps to turn the intercepted backend calls and responses into nice documentation.

Here's how mitmproxy2swagger works in practice.

Install mitimproxy2swagger. Prerequisites for this are python3 and python-pip installed

pip install mitmproxy2swagger

Clone the mitmproxy2swagger repository

git clone git@github.com:alufers/mitmproxy2swagger.git

# change directory into the repository you just cloned
cd mitmproxy2swagger

For this step, you require to have docker installed

docker build -t mitmproxy2swagger .

Start your mitmproxy and the output should be similar to the commented text below

 $ mitmweb
    # Web server listening at http://127.0.0.1:8081/
    # Proxy server listening at http://*:8080

mitmweb is a component of the mitmproxy project and it will serve to intercept the requests that will be channeled to the listener port opened at 8080

Next, we'll need to configure the requests source for which we'll use Postman

Postman is an application that allows us to do API testing. It is like a browser that doesn't render HTML. In the browser, we can hit only get HTTP requests but here we can hit get, post, put, patch, delete, and many more HTTP requests in an API.

Let's assume that we are documenting an API for a pizza restaurant:

The pizzas endpoint returns a 200 OK response with a body containing id, name, and ingredients of a pizza running at port 3000 on my local server.

Next, click on the gear icon at the top right corner of the postman interface to access the settings

On the settings pop up select proxy and then toggle use custom proxy configuration Here we'll add the proxy listener port so that Postman can channel all request through out custom proxy from mitmproxy

Now we're all set!

Let's hit the GET pizzas endpoint again

The mitm web server captures the request and response.

Next we'll need to download the file with the mitm flows and call it flows . The command below generates the first iteration

mitmproxy2swagger -i flows -o spec.yml -p http://localhost:3000 --format flow

We'll need to get rid of the ignore: prefix

Run the command again using the same file

Now we have a swagger yaml file and we can just copy it's contents and paste into the online swagger editor like this.

With this, your deadlines are saved just long enough to get some good documentation drafted.

It's been a long four minutes but thank you for getting this far. See you again when we'll be exploring other tech tools.