When it comes to documenting Application Programming Interfaces (APIs), the most popular format is the OpenAPI Specification (OAS). It provides a standardized, easy-to-read, and machine-friendly way to describe APIs. This helps developers, testers, and technical writers understand and work with your API more easily. This specification is often written in YAML, allowing automatic documentation generation, better API validation, and easy integration with tools like Mintlify and Swagger. This guide will teach you how to convert your existing API doc into OpenAPI in less than five minutes. Exporting your API Documentation As A JSON File The first step in this process is to export the API documentation. If you don't have your API documentation, use Postman to test and document the API. Make sure to add examples to each endpoint and organize them in folders for better readability and easy navigation. After you've done that, follow these processes to export the doc: At the top API folder, click on the three-dot (…)



Click on Export.



You will see a pop asking you for confirmation; click on “Export.”

This will automatically download the file to your PC as a JSON file. Converting the JSON File to An OpenAPI file Using Kevin Swiber’s Converter The second is to convert the JSON file to OpenAPI using Kevin Swiber. Go to Kevin Swiber



Open the API doc you previously downloaded from Postman, and copy the content.


Paste the content under the “Postman Collection JSON” field.



Copy the converted content under the “OpenAPI” field.

Your API documentation has been automatically converted to OpenAPI in just a few seconds. 🎉 Editing the Spec file On Swagger Editor After you've converted this file, you'll need to edit it. This is because some parameters need to be explicitly defined based on their data type, or you might want to add features that can't be included when documenting in Postman. To do this: Go to Swagger Editor
Copy and paste the OpenAPI file into the editor
Start editing the file Troubleshooting You might encounter issues like: Not all endpoints or folders are showing up
This can happen if you save your base URL as a variable when documenting your API in Postman. Go back to the file, and use the URL directly.


Swagger Editor is reloading or showing a 404 error while editing the file
If this happens, you might lose your file. To avoid this, after editing the OpenAPI for a while, copy the content and save it somewhere. You can do this every 3-5 minutes. Conclusion In this article, you've learned how to convert your API documentation to OpenAPI in just a few minutes using Kevin Swiber's OpenAPI converter. The guide also highlights potential issues you might encounter during this process and offers possible solutions to these problems. When it comes to documenting Application Programming Interfaces (APIs), the most popular format is the OpenAPI Specification (OAS). It provides a standardized, easy-to-read, and machine-friendly way to describe APIs. This helps developers, testers, and technical writers understand and work with your API more easily. This specification is often written in YAML, allowing automatic documentation generation, better API validation, and easy integration with tools like Mintlify and Swagger. This guide will teach you how to convert your existing API doc into OpenAPI in less than five minutes. This guide will teach you how to convert your existing API doc into OpenAPI in less than five minutes. This guide will teach you how to convert your existing API doc into OpenAPI in less than five minutes. Exporting your API Documentation As A JSON File The first step in this process is to export the API documentation . If you don't have your API documentation, use Postman to test and document the API. Make sure to add examples to each endpoint and organize them in folders for better readability and easy navigation. export the API documentation Postman After you've done that, follow these processes to export the doc: At the top API folder, click on the three-dot (…) Click on Export. You will see a pop asking you for confirmation; click on “Export.”

This will automatically download the file to your PC as a JSON file. At the top API folder, click on the three-dot (…) At the top API folder, click on the three-dot ( …) three-dot …) Click on Export. Click on Export. Export. You will see a pop asking you for confirmation; click on “Export.” This will automatically download the file to your PC as a JSON file. You will see a pop asking you for confirmation; click on “ Export. ” Export. This will automatically download the file to your PC as a JSON file. Converting the JSON File to An OpenAPI file Using Kevin Swiber’s Converter The second is to convert the JSON file to OpenAPI using Kevin Swiber. Go to Kevin Swiber Open the API doc you previously downloaded from Postman, and copy the content. Paste the content under the “Postman Collection JSON” field. Copy the converted content under the “OpenAPI” field.

Your API documentation has been automatically converted to OpenAPI in just a few seconds. 🎉 Go to Kevin Swiber Go to Kevin Swiber Kevin Swiber Open the API doc you previously downloaded from Postman, and copy the content. Open the API doc you previously downloaded from Postman, and copy the content. Paste the content under the “Postman Collection JSON” field. Paste the content under the “ Postman Collection JSON” field. Postman Collection JSON” Copy the converted content under the “OpenAPI” field. Your API documentation has been automatically converted to OpenAPI in just a few seconds. 🎉 Copy the converted content under the “ OpenAPI ” field. OpenAPI Your API documentation has been automatically converted to OpenAPI in just a few seconds. 🎉 Editing the Spec file On Swagger Editor After you've converted this file, you'll need to edit it. This is because some parameters need to be explicitly defined based on their data type, or you might want to add features that can't be included when documenting in Postman. To do this: Go to Swagger Editor Copy and paste the OpenAPI file into the editor Start editing the file Go to Swagger Editor Swagger Editor Copy and paste the OpenAPI file into the editor Start editing the file Troubleshooting You might encounter issues like: Not all endpoints or folders are showing up
This can happen if you save your base URL as a variable when documenting your API in Postman. Go back to the file, and use the URL directly. Swagger Editor is reloading or showing a 404 error while editing the file
If this happens, you might lose your file. To avoid this, after editing the OpenAPI for a while, copy the content and save it somewhere. You can do this every 3-5 minutes. Not all endpoints or folders are showing up This can happen if you save your base URL as a variable when documenting your API in Postman. Go back to the file, and use the URL directly. Not all endpoints or folders are showing up Not all endpoints or folders are showing up This can happen if you save your base URL as a variable when documenting your API in Postman. Go back to the file, and use the URL directly. Swagger Editor is reloading or showing a 404 error while editing the file If this happens, you might lose your file. To avoid this, after editing the OpenAPI for a while, copy the content and save it somewhere. You can do this every 3-5 minutes. Swagger Editor is reloading or showing a 404 error while editing the file Swagger Editor is reloading or showing a 404 error while editing the file If this happens, you might lose your file. To avoid this, after editing the OpenAPI for a while, copy the content and save it somewhere. You can do this every 3-5 minutes. Conclusion In this article, you've learned how to convert your API documentation to OpenAPI in just a few minutes using Kevin Swiber's OpenAPI converter. The guide also highlights potential issues you might encounter during this process and offers possible solutions to these problems.

Walkthroughs, tutorials, guides, and tips. This story will teach you how to do something new or how to do something better.

Can a Decentralized Internet Make Free Speech and Global Access a Reality?

Build a Receipt Generator with Just the Rootstock API and RPC Method

Read My Stories

Portfolio

Buy Me a Coffee

Newsletter

Technical Writer

Technical Writing Lead

Social Media Manager

Too Long; Didn't Read

How to Convert Your API Documentation to an OpenAPI in Less Than 5 Minutes

How to Convert Your API Documentation to an OpenAPI in Less Than 5 Minutes

About Author

Comments

TOPICS

THIS ARTICLE WAS FEATURED IN

Related Stories

A Beginner's Guide to Dockerizing a Vite dApp Project

100 Days of AI Day 1: From Newsletter to Podcast, Leveraging AI for Audio Transformation

10 Threats to an Open API Ecosystem

10 Indications That You Should Invest in Automation Via APIs

10 Best Practices for Securing Your API

The Noonification: Getting Your API Into Production (10/28/2022)

A Beginner's Guide to Dockerizing a Vite dApp Project

100 Days of AI Day 1: From Newsletter to Podcast, Leveraging AI for Audio Transformation

10 Threats to an Open API Ecosystem

10 Indications That You Should Invest in Automation Via APIs

10 Best Practices for Securing Your API

The Noonification: Getting Your API Into Production (10/28/2022)

Light-Mode

Classic

Newspaper

Minty

Dark-Mode

Neon Noir

Minty

HN StartUps