From 55b81d7004904337663cc8906857b9afbee4d67c Mon Sep 17 00:00:00 2001 From: "mintlify[bot]" <109931778+mintlify[bot]@users.noreply.github.com> Date: Wed, 11 Nov 2026 00:23:53 +0000 Subject: [PATCH 1/3] docs: add openapi slug option to the agent skill --- agent-context/context/skills/mintlify/reference/api-docs.md | 1 + 1 file changed, 1 insertion(+) diff --git a/agent-context/context/skills/mintlify/reference/api-docs.md b/agent-context/context/skills/mintlify/reference/api-docs.md index 2106f5aa9..d8caaf0c6 100644 --- a/agent-context/context/skills/mintlify/reference/api-docs.md +++ b/agent-context/context/skills/mintlify/reference/api-docs.md @@ -22,6 +22,7 @@ Add an `openapi` field to a navigation element (tab, group, anchor, and so on) t ``` - The value can be a path, a URL, an array of specs, or an object: `{ "source": "openapi.json", "directory": "api-reference" }`. `directory` sets where generated pages live (default `api-reference`). +- The object form also accepts `slug`, which sets the last URL segment of each generated endpoint page. `"summary"` (default) kebab-cases the operation `summary`. `"operationId"` kebab-cases the `operationId`, so `getHTTPStatusCode` becomes `get-http-status-code`, and falls back to the `summary` for operations without one. `directory` and tag folders don't change, page titles still come from the `summary`, and nested groups inherit `slug` along with the spec. Changing `slug` on a live site changes endpoint URLs, so add redirects from the old paths. - To mix endpoints with other pages, set `openapi` on the element and list endpoints in `pages` as `METHOD /path`. Child elements inherit the parent's spec unless they set their own. - To pull an endpoint from a specific spec without a default, use `"/path/to/spec.json POST /users"` as the page entry. - `api.openapi` in `docs.json` accepts the same values. From 1c82caab8ba3976a576ad8a988851ba5477ad815 Mon Sep 17 00:00:00 2001 From: "mintlify[bot]" <109931778+mintlify[bot]@users.noreply.github.com> Date: Wed, 11 Nov 2026 00:29:33 +0000 Subject: [PATCH 2/3] docs: show slug in a full openapi object example in the agent skill --- agent-context/context/skills/mintlify/reference/api-docs.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/agent-context/context/skills/mintlify/reference/api-docs.md b/agent-context/context/skills/mintlify/reference/api-docs.md index d8caaf0c6..c1d3367ee 100644 --- a/agent-context/context/skills/mintlify/reference/api-docs.md +++ b/agent-context/context/skills/mintlify/reference/api-docs.md @@ -22,7 +22,7 @@ Add an `openapi` field to a navigation element (tab, group, anchor, and so on) t ``` - The value can be a path, a URL, an array of specs, or an object: `{ "source": "openapi.json", "directory": "api-reference" }`. `directory` sets where generated pages live (default `api-reference`). -- The object form also accepts `slug`, which sets the last URL segment of each generated endpoint page. `"summary"` (default) kebab-cases the operation `summary`. `"operationId"` kebab-cases the `operationId`, so `getHTTPStatusCode` becomes `get-http-status-code`, and falls back to the `summary` for operations without one. `directory` and tag folders don't change, page titles still come from the `summary`, and nested groups inherit `slug` along with the spec. Changing `slug` on a live site changes endpoint URLs, so add redirects from the old paths. +- The object form also accepts `slug`: `{ "source": "openapi.json", "directory": "api-reference", "slug": "operationId" }`. `slug` sets the last URL segment of each generated endpoint page: `"summary"` (default) kebab-cases the operation `summary`, and `"operationId"` kebab-cases the `operationId` (falling back to the `summary` when an operation has none). Changing `slug` on a live site changes endpoint URLs, so add redirects from the old paths. - To mix endpoints with other pages, set `openapi` on the element and list endpoints in `pages` as `METHOD /path`. Child elements inherit the parent's spec unless they set their own. - To pull an endpoint from a specific spec without a default, use `"/path/to/spec.json POST /users"` as the page entry. - `api.openapi` in `docs.json` accepts the same values. From 043ddef884fe71b424d51f83240cf03c57ad95bf Mon Sep 17 00:00:00 2001 From: "mintlify[bot]" <109931778+mintlify[bot]@users.noreply.github.com> Date: Wed, 11 Nov 2026 00:39:18 +0000 Subject: [PATCH 3/3] docs: shorten the openapi slug note in the agent skill --- agent-context/context/skills/mintlify/reference/api-docs.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/agent-context/context/skills/mintlify/reference/api-docs.md b/agent-context/context/skills/mintlify/reference/api-docs.md index 5012bc595..a35831cad 100644 --- a/agent-context/context/skills/mintlify/reference/api-docs.md +++ b/agent-context/context/skills/mintlify/reference/api-docs.md @@ -22,7 +22,7 @@ Add an `openapi` field to a navigation element (tab, group, anchor, and so on) t ``` - The value can be a path, a URL, an array of specs, or an object: `{ "source": "openapi.json", "directory": "api-reference" }`. `directory` sets where generated pages live (default `api-reference`). -- The object form also accepts `slug`: `{ "source": "openapi.json", "directory": "api-reference", "slug": "operationId" }`. `slug` chooses which field of each OpenAPI operation becomes the last URL segment of its generated page, and accepts two values: `"summary"` (default) or `"operationId"`. For example, an untagged operation with `operationId: listUsers` and `summary: Get all users` gets `/api-reference/list-users` with `"slug": "operationId"`, and `/api-reference/get-all-users` by default. Operations without an `operationId` use their `summary`. Changing `slug` on a live site changes endpoint URLs, so add redirects from the old paths. +- The object form also accepts `slug`: `{ "source": "openapi.json", "directory": "api-reference", "slug": "operationId" }`. `slug` sets which operation field generates endpoint page URLs: `"summary"` (default) or `"operationId"`. - To mix endpoints with other pages, set `openapi` on the element and list endpoints in `pages` as `METHOD /path`. Child elements inherit the parent's spec unless they set their own. - To pull an endpoint from a specific spec without a default, use `"/path/to/spec.json POST /users"` as the page entry. - `api.openapi` in `docs.json` accepts the same values.