Automated API Documentation: A Step-by-Step Guide
I’m about halfway through APIsec University’s API Penetration Testing course, and I’m already learning a lot about testing APIs for security vulnerabilities. The course teaches particular tools and procedures for evaluating, testing, and discovering API vulnerabilities. So far, I’ve learned how to use API reconnaissance and reverse APIs to make useful documentation. The course is a great way to learn how to make API documentation automatically. As a penetration tester, it’s very hard to test APIs because there isn’t much or any good API documentation. I’m writing this blog to make creating automated API documentation easier.
Step 1: Starting mitmweb
Install mitmweb from the terminal, and then start it. When mitmweb starts, it starts the web server on port 8081 and proxy starts listening on port 8080.
Step 2: Configure Proxy for Device or Browser
You can use foxyproxy or manually set up the proxy on your browser or device to send traffic through port 8080.
Step 3: Explore the Website
In this step, you can look around the website as much as you like. Press every button. Check out each page. Leave no pages untouched. During the process, the traffic will be captured and the mitmproxy will be filled.
Step 4: Save Captured Flows
When you’ve done everything you can with your target web app, go back to the mitmweb web server and click File > Save to save the requests you captured.
If you choose Save, a file called flows will be made. Now that we have the “flows” file, we can use it to write our own API documentation.
Step 5: mitmproxy2swagger
Install mitmproxy2swagger. This is a tool that converts mitmproxy captures to OpenAPI 3.0 specifications automatically. This means that you can automatically reverse-engineer REST APIs by running the apps and capturing the traffic.
Ref: https://github.com/alufers/mitmproxy2swagger
Step 6: Generate, Review, Edit Swagger YAML File
Use the following terminal command –
mitmproxy2swagger -i <path_to_mitmptoxy_flow> -o <path_to_output_schema> -p <api_prefix> [--examples]
It will create a YAML file. After executing this, you must change the spec.yml file to determine whether mitmproxy2swagger ignored too many endpoints. Checking spec.yml indicates that numerous endpoints were disregarded, and the file’s title may be modified.
Remove “ignore:” from the endpoints that you want to include from the YAML file. Note that “ignore:” is no longer present in the endpoints. Save the modified spec.yml file and run mitmproxy2swagger once again. This time, add the —examples switch to your API documentation to improve it.
Step 7: Import the YAML file in Swagger Editor and Postman to Test Endpoints
Head over to https://editor.swagger.io/ and Upload the YAML file.
Also, you can import it to Postman and the Test the API Endpoints.
Conclusion
In conclusion, automated API documentation with tools such as mitmproxy2swagger and Postman may considerably accelerate the API testing process by providing developers and testers with an organized and readily available documentation of API endpoints. By following the step-by-step approach, you may record API flows, build a Swagger YAML file, change and evaluate it, and then import it into Postman for API endpoint testing. This strategy is particularly beneficial for large-scale API penetration testing and bug bounty programs, and it may save a great deal of time and effort. Always keep security in mind while doing API testing; thus, be sure to examine and remedy any vulnerabilities or flaws you discover.