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

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:

1. At the top API folder, click on the three-dot (…)

   

2. Click on Export.

   

3. 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.

1. Go to Kevin Swiber

   

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

   
   

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

   

4. 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:

1. Go to Swagger Editor
2. Copy and paste the OpenAPI file into the editor
3. Start editing the file

Troubleshooting

You might encounter issues like:

1. 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.

   
   

2. 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.