In the previous article of this series, we learned how to create the documentation for your API using OpenAPI.
If you didn't check it out, what are you waiting for !?!? 😁😁
Today we will see in this brief tutorial how to create a Postman collection from this documentation.
Download API docs
We have different ways to download the YAML file containing the documentation. It depends on how we stored it.
Swagger Editor
Swagger Editor stores the status of your last edition. Yet, if you have to delete information from your browser, all your progress may be lost! 🆘🆘
Swagger Editor is an excellent tool for fast edition and linting your files. However, if the documentation is large and will take you days, then use editors like Notepad++, Gedit, or VSCode to write it.
To download the API documentation file from Swagger Editor, we have to click on: Edit-> Save as YAML
The browser will download an openapi.yaml file.
SwaggerHub
Swagger Hub stores the information on their servers. There is nothing to worry about here 🤗 To download it, we have to click on our API project.
Once we are editing our project, we have to click on Export -> Download API -> YAML Resolved.
I think this is the best format to do so. JSON will be valid as well, although I find YAML easier to edit.
Import it to Postman
Now, go on and open Postman. If you don't have it, you can download it from this link.
We are going to select the APIs tab.
Then let's click on Import and select the OpenAPI docs file. Confirm that you want the Collection to act as Documentation
If you check the APIs section, the definition of your OpenAPI Documentation should appear.
Moreover, the generated collection will appear in the Collections tab. You should see something like this:
Create a Mock Server in Swaggerhub
Do you have a server to make requests to? NO? LET'S MOCK IT THEN!
Before testing our API, we have to create a Mock Server to make requests to! To do so, we are going to take advantage of the Integrations available at SwaggerHub.
Click on your API name inside the editor and delete Integrations tab.
Then, add new integration and select API Auto Mocking
Set your API name to whatever you want. In this case, I defined Idea API.
Now the integration is completed. We have our mock server up and running! The address has the following format:
https://virtserver.swaggerhub.com/<owner>/<api-name>/<version>
In my case, this results in https://virtserver.swaggerhub.com/victorgarciar/idea-api/1.0.0
Test!
You can't say "It works!" if you haven't tested it yourself
Let's go back to our Postman Collection and set the "baseUrl" variable to the URL of our mock server.
Click on the Collection's name and select the Variables tab. You will have a variable there named "baseUrl" as mentioned. Delete the current value and paste your mock server URL!
Now we have everything set up! Go to one of the requests and send it. You should see something like this:
Of course, results will make no sense since we are using a mock server. Don't forget!
Summary
In this article, I hope you have learned:
- Downloading your API docs
- Importing it to Postman
- Creating a mock server in SwaggerHub
- Test your API with a mock server
I am HONOURED if you have reached this point. Thanks a lot for reading 💙
Hopefully, I was able to explain how to import OpenAPI docs to Postman and create a Mock Server in SwaggerHub to test it!
Reach out on Twitter to find more valuable content or just chatting!
😼 https://github.com/victorgrubio
References
Thanks and Keep It Up! 🦾🦾
Top comments (1)
Good article! And here you can check PandaDoc public workspace that was featured by the Postman Staff medium.com/the-pandadoc-tech-blog/...