How To Upload Your OpenAPI Specification to Mintlify

Introduction

Mintlify is a documentation tool that facilitates the creation, management, and publishing of interactive documentation. It offers a range of customization tools and features, enabling users to create visually appealing documentation.

If you want to leverage these dynamic and customizable features by uploading your OpenAPI Specification On Mintlify, then this article is for you.

This article will walk you through the step-by-step process of how to upload your OpenAPI specification to Mintlify.

Prerequisites

To upload your OpenAPI specification to Mintlify, ensure you have the following:

• Mintlify Account

• GitHub

• VS Code

• Node.js

After you have set these up, follow these steps to upload your OpenAPI specification on Mintlify:

Step 1: Log in or sign up for an account on Mintlify.

Step 2: Sign in with your GitHub.

Step 3: Click ‘Next’ to create a documentation repository.

Step 4: Click ‘Go to dashboard’.

This should appear on your screen.

Step 5: Click the ‘Settings’ section and navigate to the ‘GitHub App.’ Then click 'Install GitHub App.’

This enables automatic deployment of your documentation updates whenever you push changes to your repository.

Step 6: Select the repository you just created and click ‘Save.’

The next step is to set up your code environment in VSCode.

Step 7 Navigate to the documentation repository in GitHub.

Step 8: Click the ‘Code’ button, select the HTTPS option, and copy the URL.

Step 9: Create a new folder on Vscode.

Step 10: Open your terminal and enter git clone https://github.com/YOUR-USERNAME/YOUR-REPOSITORY. Replace this with the URL you copied.

Step 11: Enter cd mintlify-docs to navigate to the project directory.

Step 12 Enter npm install -g mintlify to install Mintlify.

After successfully installing Mintlify and a copy of the starter kit on your local machine, the next step is to auto-populate your API pages using the OpenAPI specification.

How to Auto-Populate API Pages

Follow these steps to auto-populate your API pages on Mintlify:

Step 1: Delete the endpoint file in the folder. This represents the dummy template that came pre-installed with the starter kit.

Step 2: Create a YAML file inside the api-reference folder. Then paste your OpenAPI specification file in it.

Step 3: Click the docs.json file. This represents the core configuration file that contains the structure, styling, and navigation of your documentation site.

Step 4: Navigate to the API Reference tab in docs.json. Create an OpenAPI object in the tab by pasting this code after the tab.

"openapi": {

"source": "/api-reference/openapi.yaml",

"directory": "api-reference"

},

You should have something like this:

Step 5: Enter this command in your terminal npx @mintlify/scraping@latest openapi-file ./api-reference/openapi.yaml

All endpoints in the OpenAPI specification should automatically be generated.

The next step is to push your documentation to Git. This is one of the perks that Mintlify offers, allowing you to preview changes to your documentation in a live environment. It also allows you to track changes, revert to previous versions, and seamlessly collaborate with teammates.

How to push your Documentation to Git

Follow these steps to push your documentation to Git:

Step 1: Enter git add .

Step 2: Enter git commit -m “first commit” to commit your changes.

Step 3: Enter git push origin main to push to your repository.

The next step is to view your live documentation

Step 4: Navigate to your dashboard on Mintlify.

Step 5: Click ‘Visit docs’ to view your live documentation.

Step 6: Click the ‘API-reference’ tab to view your documentation.

This should appear on your screen

Notice: All your endpoints are now displayed.

You have successfully migrated your documentation to Mintlify!

Next Steps

After successfully uploading your OpenAPI specification on Mintlify, you can proceed to add more customization to make your documentation visually appealing. This may include adding a customized logo and color, dropdowns, images, and more. Check this guide to get started.