Table of contents
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.