Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Improve Documentation Structure for Better LLM Indexing #561

Open
wants to merge 1 commit into
base: main
Choose a base branch
from
Open

Improve Documentation Structure for Better LLM Indexing #561

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
257 changes: 128 additions & 129 deletions api-playground/openapi/setup.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -3,157 +3,156 @@ title: "OpenAPI Setup"
description: "Reference OpenAPI endpoints in your docs pages"
---

## Add an OpenAPI specification file
## Getting Started with OpenAPI Integration

To describe your endpoints with OpenAPI, make sure you have a valid OpenAPI
document in either JSON or YAML format that follows the
[OpenAPI specification](https://swagger.io/specification/). Your document must
follow OpenAPI specification 3.0+.
<Tip>To validate your OpenAPI spec, use our [CLI](https://www.npmjs.com/package/mintlify) and run this command: <br/>`mintlify openapi-check <openapiFilenameOrUrl>`</Tip>
### Prerequisites
Before integrating OpenAPI into your documentation, ensure you have:

## Auto-populate API pages
- A valid OpenAPI document (JSON or YAML format)
- OpenAPI specification 3.0 or higher
- [Mintlify CLI](https://www.npmjs.com/package/mintlify) installed

The fastest way to get started with OpenAPI is to add an `openapi` field to a tab in the `docs.json`. This field can contain either the path to an OpenAPI document in your docs repo, or the URL of a hosted OpenAPI document. Mintlify will automatically generate a page for each OpenAPI operation and place them in the tab.
<Tip>
Validate your OpenAPI specification using our CLI:
```bash
mintlify openapi-check <openapiFilenameOrUrl>
```
</Tip>

## Implementation Methods

### Method 1: Auto-population with Navigation Tabs

The quickest way to implement OpenAPI is through your `docs.json` configuration. You can either reference a local file or a hosted URL.

**Example with Tabs:**
```json {5}
"navigation": {
"tabs": [
{
<CodeGroup>
```json Tab-Based Navigation
{
"navigation": {
"tabs": [
{
"tab": "API Reference",
"openapi": "https://petstore3.swagger.io/api/v3/openapi.json"
}
]
}
]
}
}
```
![](/images/autogeneration-with-tabs.png)

**Example with Groups:**
```json {8-11}
"navigation": {
"tabs": [
{
"tab": "API Reference",
"groups": [
{
"group": "Endpoints",
"openapi": {
"source": "/path/to/openapi-1.json",
"directory": "api-reference"

```json Group-Based Navigation
{
"navigation": {
"tabs": [
{
"tab": "API Reference",
"groups": [
{
"group": "Endpoints",
"openapi": {
"source": "/path/to/openapi-1.json",
"directory": "api-reference"
}
}
}
]
}
]
]
}
]
}
}
```

When using this option, the metadata for the generated pages will have the following default values:

* `title`: The `summary` field from the OpenAPI operation, if present. Otherwise a title generated from the HTTP method and endpoint.

* `description`: The `description` field from the OpenAPI operation, if present.

* `version`: The `version` value from the anchor or tab, if present.

There are some scenarios in which the default behavior isn't sufficient. If you need more customizability, you can create an MDX page for your OpenAPI operation, and modify it just like any other MDX page.

## Create MDX files for API pages

If you want to customize the page metadata, add additional content, omit certain OpenAPI operations, or reorder OpenAPI pages in your navigation, you'll need an MDX page for each operation. Here is [an example MDX OpenAPI page](https://github.com/mindsdb/mindsdb/blob/main/docs/rest/databases/create-databases.mdx) from [MindsDB](https://docs.mindsdb.com/rest/databases/create-databases).&#x20;

![](/images/mindsdb.png)

### Manually specify files

You can always create an MDX page manually, and reference the OpenAPI operation in the page's metadata using the `openapi` field.

<Snippet file="api-playground/openapi.mdx" />

By using the OpenAPI reference, the name, description, parameters, responses,
and the API playground will be automatically generated from the OpenAPI document.

If you have multiple OpenAPI files, include the path to the OpenAPI file to ensure Mintlify finds the correct OpenAPI document. This is not required if you have
only one OpenAPI file - it will automatically detect your OpenAPI file.

<CodeGroup>
```md Example
---
title: "Get users"
openapi: "/path/to/openapi-1.json GET /users"
---
```

```md Format
---
title: "title of the page"
openapi: openapi-file-path method path
---
```
</CodeGroup>

<br />
<Info>
Auto-generated pages will use the following metadata by default:
- **Title**: OpenAPI operation summary or generated from HTTP method/endpoint
- **Description**: OpenAPI operation description
- **Version**: Version value from the anchor/tab (if present)
</Info>

### Method 2: Custom MDX Pages

For more control over your API documentation, you can create individual MDX pages for each operation.

<Steps>
<Step title="Create an MDX File">
Create a new MDX file for your API endpoint. Here's an example structure:
```md
---
title: "Get users"
openapi: "/path/to/openapi-1.json GET /users"
---
```
</Step>

<Step title="Specify OpenAPI Reference">
The `openapi` field format should follow:
```
openapi: <file-path> <method> <path>
```

<Note>
If you only have one OpenAPI file, the file path is optional - Mintlify will automatically detect it.
</Note>
</Step>

<Step title="Add Custom Content">
Add any additional content or customization below the frontmatter.
</Step>
</Steps>

<Warning>
The method and path must exactly match those in your OpenAPI document. For webhooks, use "webhook" instead of the HTTP method (e.g., "POST").
</Warning>

### Method 3: Automated File Generation

For large OpenAPI documents, use our scraping tool to automatically generate MDX files.

<Steps>
<Step title="Install the Scraper">
Use our [@mintlify/scraping](https://www.npmjs.com/package/@mintlify/scraping) package:
```bash
npx @mintlify/scraping@latest openapi-file <path-to-openapi-file>
```
</Step>

<Step title="Specify Output Directory">
Add the `-o` flag to choose where files are generated:
```bash
npx @mintlify/scraping@latest openapi-file <path-to-openapi-file> -o api-reference
```
</Step>

<Step title="Update Navigation">
Add the generated navigation entries to your configuration:
- Append them to existing navigation, or
- Manually organize them in your preferred structure
</Step>
</Steps>

<Note>
In most cases, the method and path must match the method and path specified
in the OpenAPI document exactly. If the endpoint doesn't exist in the OpenAPI
file, the page will be empty.

For webhooks, replace the method (i.e. "POST") with "webhook" (case insensitive)
and the correct method will be generated.
The scraper requires a valid OpenAPI document. Invalid specifications will not generate files.
</Note>

### Autogenerate files

For large OpenAPI documents, creating one MDX page for each OpenAPI operation can be a lot of work. To make it easier, we created a local OpenAPI page scraper.

Our Mintlify [scraper](https://www.npmjs.com/package/@mintlify/scraping)
autogenerates MDX files for your OpenAPI endpoints.
## Working with OpenAPI Schemas

Each generated page will correspond to an OpenAPI operation under the "paths" section of the OpenAPI schema.
If your OpenAPI document is version 3.1+, the scraper will also generate pages for webhooks under the "webhooks" section of the OpenAPI schema.
### Individual Schema Pages

Create dedicated pages for schemas defined in your OpenAPI document's `components.schemas`:

```bash
npx @mintlify/scraping@latest openapi-file <path-to-openapi-file>
<CodeGroup>
```md Example
---
openapi-schema: OrderItem
---
```

Add the `-o` flag to specify a folder to populate the files into. If a folder is
not specified, the files will populate in the working directory.

```bash
npx @mintlify/scraping@latest openapi-file <path-to-openapi-file> -o api-reference
```md Format
---
openapi-schema: "schema-key"
---
```
</CodeGroup>

Learn more about our scraping package [here](https://www.npmjs.com/package/@mintlify/scraping).

The scraper will output an array of
[Navigation entries](/settings/global#structure) containing your OpenAPI MDX
files. You can either append these entries to your existing Navigation, or
reorder and add the files to your navigation manually.

<Note>
If your OpenAPI document is invalid, the files will not autogenerate.
</Note>



## Create MDX files for OpenAPI schemas

Mintlify also allows you to create individual pages for any OpenAPI schema
defined in an OpenAPI document's `components.schemas` field:

<CodeGroup>
```md Example
---
openapi-schema: OrderItem
---
```

```md Format
---
openapi-schema: "schema-key"
---
```
</CodeGroup>
<Info>
Schema pages automatically inherit documentation from your OpenAPI specification while allowing you to add custom content and examples.
</Info>
19 changes: 14 additions & 5 deletions docs.json
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -22,7 +22,11 @@
{
"group": "Editing",
"icon": "pen-paintbrush",
"pages": ["development", "web-editor"]
"pages": [
"development",
"web-editor",
"quickstart"
]
},
"settings/global",
{
Expand All @@ -37,7 +41,9 @@
]
},
"themes",
"migration"
"migration",
"text",
"settings/global"
]
},
{
Expand All @@ -61,7 +67,8 @@
"pages": [
"api-playground/openapi/setup",
"api-playground/openapi/writing-openapi",
"api-playground/openapi/advanced-features"
"api-playground/openapi/advanced-features",
"api-playground/openapi/setup"
]
},
{
Expand Down Expand Up @@ -263,7 +270,9 @@
"groups": [
{
"group": "Changelog",
"pages": ["changelog/overview"]
"pages": [
"changelog/overview"
]
}
]
}
Expand Down Expand Up @@ -375,4 +384,4 @@
"publicApiKey": "pk_76a6caa274e800f3ceff0b2bc6b9b9d82ab8"
}
}
}
}
Loading