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 thepnpm run dev
command from a terminal within the docs
directory.
Docs structure
The docs root directory is structured as follows: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 thegenerate-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, For sake of simplicity, copy this navigation object suggestion and add it your
@mintlify/scraping
helpfully outputs the suggested navigation to the terminal:mint.json
under the navigation
object:2
Add OpenAPI endpoint to `mint.json`
Add the This enables the generated MDX files to describe and interact with your API.
openapi
key to your mint.json
. This, preferably, can be linked to your published OpenAPI schema: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
create an
openapi.json
file in the docs
root. Manually copy and paste/save your openapi.json
into this file.