Documentation config

Mintlify setup and configuration

Introduction

The documentation site is built entirely using Mintlify. Mintlify docs are rendered from MDX files and configurations. Mintlify works with a Github integration to constantly build an independent docs site based off your latest published repository.

Documentation can be edited in raw MDX, or directly through the Mintlify dashboard (which stays in sync with your local Github repo).

Mintlify is fast to setup and provides tonnes of features out-the-box without the need to pay for a subscription for the basic services.

You can run the docs site only by running the pnpm run dev command from a terminal within the docs directory.

Docs structure

The docs root directory is structured as follows:

docs
├── _images
├── api
├── configuration
├── deployment
├── logos
├── *.mdx
├── mint.json
└── package.json

The docs directory is relatively simple and is made mostly of MDX files. Some notable files are:

Item	Description
api	Automatically generated files (except for Introduction.mdx)
mint.json	Mintlify configuration object
package.json	Scripts needed in the monorepo/for generating the API files

Creating API endpoint documentation

We can leverage FastAPI’s baked in OpenAPI support to automatically generate API documentation.

Using Mintlify’s @mintlify/scraping package, we can scrape our FastAPI’s OpenAPI schema to generate an interactive API documentation site.

For a more detailed description, read the official documentation

Generating OpenAPI schema

Step 1: Generate MDX

Run the generate-api scripts within the package.json to generate the required MDX files. There are two scripts here, one configured to use the production OpenAPI.json and the second configured to use the development version.

It is typically preferred to use the production version once any changes to your API have been made and published.

Step 2: Update mint.json

1. Add new MDX files to navigation

   Upon generating the relevant API information, @mintlify/scraping helpfully outputs the suggested navigation to the terminal:

   navigation object suggestion:
   [
     {
       "group": "users",
       "pages": [
         "api/users/get-user",
         "api/users/get-all-users",
         "api/users/search-users",
         "api/users/create-user"
       ]
     },
     {
       "group": "spells",
       "pages": [
         "api/spells/get-spell",
         "api/spells/get-all-spells",
         "api/spells/search-spells"
       ]
     }
   ]
   

   For sake of simplicity, copy this navigation object suggestion and add it your mint.json under the navigation object:

   "navigation": [
     {
       "group": "Getting Started",
       "pages": ["documentation/introduction", "documentation/local-development"]
     },
     {
       "group": "Configuration",
       "pages": [
         "documentation/configuration/turbo",
         "documentation/configuration/fastapi",
         "documentation/configuration/nextjs",
         "documentation/configuration/docs"
       ]
     },
     {
       "group": "Deployment",
       "pages": [
         "documentation/deployment/vercel",
         "documentation/deployment/deployment"
       ]
     },
     {
       "group": "API Reference",
       "pages": ["api/introduction"]
     },
     {
       "group": "Users",
       "pages": [
         "api/users/get-user",
         "api/users/get-all-users",
         "api/users/search-users",
         "api/users/create-user"
       ]
     },
     {
       "group": "Spells",
       "pages": [
         "api/spells/get-spell",
         "api/spells/get-all-spells",
         "api/spells/search-spells"
       ]
     }
   ],
   

2. Add OpenAPI endpoint to `mint.json`

   Add the openapi key to your mint.json. This, preferably, can be linked to your published OpenAPI schema:

   {
     ...
     "openapi":"https://next-fast-turbo-api.vercel.app/openapi.json"
     ...
   }
   

   This enables the generated MDX files to describe and interact with your API.

   This has been hit and miss in the past for me. If doing this does not auto-populate your API reference with the documentation, the solution is to manually
   create an openapi.json file in the docs root. Manually copy and paste/save your openapi.json into this file.