From f09fca18bd02674fcded22e01aa1233723f1ab80 Mon Sep 17 00:00:00 2001 From: "mintlify[bot]" <109931778+mintlify[bot]@users.noreply.github.com> Date: Thu, 20 Nov 2025 20:02:34 +0000 Subject: [PATCH 1/3] Update api-playground/openapi-setup.mdx --- api-playground/openapi-setup.mdx | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/api-playground/openapi-setup.mdx b/api-playground/openapi-setup.mdx index 978a715ce..513a29de3 100644 --- a/api-playground/openapi-setup.mdx +++ b/api-playground/openapi-setup.mdx @@ -259,6 +259,10 @@ Add an `openapi` field to any navigation element in your `docs.json` to automati The `openapi` field accepts either a file path in your docs repo or a URL to a hosted OpenAPI document. + + **Setting the `openapi` property on an anchor, tab, or group automatically generates pages for ALL endpoints in the OpenAPI specification.** This can significantly change your navigation structure and may be a breaking change if you have existing links or bookmarks to specific pages. + + Generated endpoint pages have these default metadata values: - `title`: The operation's `summary` field, if present. If there is no `summary`, the title is generated from the HTTP method and endpoint. From b1e14e0f2530a58b2fb028bcf8505cf97db1da6d Mon Sep 17 00:00:00 2001 From: "mintlify[bot]" <109931778+mintlify[bot]@users.noreply.github.com> Date: Thu, 20 Nov 2025 20:02:42 +0000 Subject: [PATCH 2/3] Update api-playground/openapi-setup.mdx --- api-playground/openapi-setup.mdx | 6 +++++- 1 file changed, 5 insertions(+), 1 deletion(-) diff --git a/api-playground/openapi-setup.mdx b/api-playground/openapi-setup.mdx index 513a29de3..35d4d5779 100644 --- a/api-playground/openapi-setup.mdx +++ b/api-playground/openapi-setup.mdx @@ -281,7 +281,11 @@ There are two approaches for adding endpoint pages into your documentation: ### Dedicated API sections -Generate dedicated API sections by adding an `openapi` field to a navigation element and no other pages. All endpoints in the specification are included. +Generate dedicated API sections by adding an `openapi` field to a navigation element and no other pages. **All endpoints in the specification are automatically included.** + + + When you add an `openapi` field to a navigation element without specifying individual pages, every endpoint defined in that OpenAPI specification will generate a page in your documentation. Review your specification to ensure you want all endpoints to be publicly documented. + ```json {5} "navigation": { From 9d56a534dfa6c7014604688441f57781b853ca8c Mon Sep 17 00:00:00 2001 From: "mintlify[bot]" <109931778+mintlify[bot]@users.noreply.github.com> Date: Thu, 20 Nov 2025 20:02:52 +0000 Subject: [PATCH 3/3] Update api-playground/openapi-setup.mdx --- api-playground/openapi-setup.mdx | 6 +++++- 1 file changed, 5 insertions(+), 1 deletion(-) diff --git a/api-playground/openapi-setup.mdx b/api-playground/openapi-setup.mdx index 35d4d5779..dc2034267 100644 --- a/api-playground/openapi-setup.mdx +++ b/api-playground/openapi-setup.mdx @@ -298,7 +298,7 @@ Generate dedicated API sections by adding an `openapi` field to a navigation ele } ``` -To organize multiple OpenAPI specifications in separate sections of your documentation, assign each specification to a different group in your navigation hierarchy. Each group can reference its own OpenAPI specification. +To organize multiple OpenAPI specifications in separate sections of your documentation, assign each specification to a different group in your navigation hierarchy. **Each group with an `openapi` field generates pages for all endpoints in its respective specification.** ```json {8-11, 15-18} "navigation": { @@ -326,6 +326,10 @@ To organize multiple OpenAPI specifications in separate sections of your documen } ``` + + In this example, the "Users API" group will generate pages for **every endpoint** in `users-openapi.json`, and the "Admin API" group will generate pages for **every endpoint** in `admin-openapi.json`. If you only want to include specific endpoints, use the [selective endpoints](#selective-endpoints) approach instead. + + The `directory` field is optional and specifies where generated API pages are stored in your docs repo. If not specified, defaults to the `api-reference` directory of your repo.