openapi field to any navigation element in your docs.json, such as a tab, anchor, or group, to generate endpoint pages from a specification. The openapi field accepts a path in your docs repository or the URL of a hosted specification.
You can add endpoints in two ways:
- Generate a section from a whole specification. Every endpoint gets a page, grouped by tag. Use this for most API references.
- List specific endpoints. Only the endpoints you list get pages, in the order you list them, alongside your other pages.
Generate a section from a specification
Add anopenapi field to a navigation element with no pages. Every endpoint in the specification gets a page in that element.
docs.json
Rename tag groups
By default, a group’s label is its tagname. To show a different label, add x-group to the tag. The URL still uses the tag name.
x-group, Mintlify uses its x-displayName extension as the label, so specifications that already use x-displayName need no changes. If a tag has both, x-group wins.
Nest groups with tag hierarchies
In OpenAPI 3.2 documents, tags can declareparent, kind, and summary fields. Mintlify uses them to build nested groups. OpenAPI 3.0 and 3.1 documents keep one flat group per tag.
parent: Nests the tag’s group inside the parent tag’s group.summary: Sets the group label. If a tag also hasx-grouporx-displayName, the extension wins, withx-groupfirst.kind: Controls how Mintlify uses the tag.navor nokind: Creates a navigation group.badge: Shows the tag’ssummary, or itsnameif there is nosummary, as a pill next to the endpoint in the sidebar. Badge tags don’t create groups.- Any other value, such as
audience: Creates neither a group nor a pill.
kind: nav. If there is none, Mintlify uses the first declared tag with no kind, and then the first tag that isn’t declared in tags. To set a different pill for one endpoint, use tag in x-mint.metadata, which takes precedence over badge tags.
Validation fails if two tags share a name, if a parent references a tag that doesn’t exist, or if parent references form a cycle.
List specific endpoints
To choose which endpoints get pages and where they go, set a defaultopenapi on a navigation element and list endpoints in its pages as METHOD /path. You can mix endpoints with other pages.
docs.json
openapi:
docs.json
docs.json
pages entry that doesn’t match an operation as a file path. HTTP methods must be uppercase.
Use multiple specifications
To generate pages from more than one specification, put each specification on its own navigation element, and give each one its owndirectory. If you set openapi to an array, Mintlify generates pages only from the first specification in the array.
docs.json
directory sets the folder in the URL of each generated page. If two specifications share a directory and produce the same page URL, one page silently replaces the other. See Endpoint URLs and titles.
Organize a large specification
Mintlify doesn’t read thex-tagGroups extension. For a specification with many tags, pick one approach:
- One specification per section. Split the specification into one file per product area, or use overlays to remove the operations that don’t belong in each section, then give each its own section.
- Tag hierarchies. Upgrade to OpenAPI 3.2 and nest tags under parent tags.
- List endpoints. List each endpoint in your
docs.jsonin the groups you want. This gives you full control, but you must add new endpoints todocs.jsonyourself.
Hide or exclude endpoints
Addx-hidden or x-excluded to an operation or webhook to keep it out of your generated navigation:
x-hidden: true: The endpoint gets a page, but the page doesn’t appear in the navigation. Anyone with the URL can open it. Use this for endpoints you link to from other pages or share with specific users.x-excluded: true: The endpoint doesn’t get a page. Use this for internal endpoints, or endpoints that aren’t ready to document.
x-excluded only removes the page. If visitors can access your specification file, excluded endpoints are still in it.
To show endpoints only to specific user groups, add x-mint.groups to the operation. See OpenAPI content filtering.