This post is a follow up to my earlier Build an OpenAPI 3.0 documentation file post.
In this previous post, I showed you how you can create your own API documentation, compliant with the OpenAPI 3.0 specifications, using Firefox and mitmproxy2swagger.
The point is to have a documentation file that you can then import into Postman as a collection and then start testing the target API for vulnerabilities.
Starting in Postman
If this remains a valid workflow, I prefer to actually build a collection directly in Postman. To do this, I set up Firefox to proxy its traffic into Postman (using a tool such as FoxyProxy). I also start the proxy in Postman to capture the incoming traffic.
I then explore the target web application in Firefox, visiting all the pages and trying out all the features (create/modify user accounts, add pictures, download files, upload files, etc). You know the drill.
You will see the corresponding requests populate the request window in Postman as you go.
I then filter out the unnecessary requests and build my own collection in Postman, ready for me to investigate each request individually.
All this is good, but if you want to take things further, you may also want to generate an OpenAPI 3.0 documentation for your target API’s collection you just created in Postman.
Why would you want to do that?
Well, if you are working in a team, with your teammates maybe using different sets of tools, you will need to distribute a documentation that everyone can use the way they want, in a format that everyone is comfortable with.
Also, like myself, you may prefer to review your documentation in a tool such as Swagger Editor that provides just the right interface to do this.
And also, you may want to search through you target API’s requests using a tool such as gron (more on this one in a later post).
Export a collection from Postman
In Postman, select the Collection tab. Now right-clic on the collection you want to convert and select Export.
Export in Collection v2.1 format. You’ll get a file with a .json extension.
Installing postman2openapi
You now need to convert this file into yaml format. To do this, you will use postman2openapi, that you can download here.
Move the file you just downloaded into /usr/local/bin and unzip it using:
sudo tar -xvf postman2openapi-1.0.0-x86_64-unknown-linux-musl.tar.gz
Then move the postman2openapi app one step up so it’s directly in /usr/local/bin.
Using postman2openapi
Navigate to where your Postman collection export is located and run:
postman2openapi filename.json > filename.yaml
(Assuming filename.json is the name of your file).
To check the documentation you just created, start your browser, open Swagger Editor, then open your yaml file with File > Import file.
You can then review each request individually. Enjoy!
