@@ -120,37 +132,35 @@ To enable authentication in your API documentation and playground, configure the
- Add a `securitySchemes` field to define how users authenticate.
+ Add a `securitySchemes` field to define how users authenticate.
- This example shows a configuration for bearer authentication.
+ This example shows a configuration for bearer authentication.
- ```json
- {
- "components": {
- "securitySchemes": {
- "bearerAuth": {
- "type": "http",
- "scheme": "bearer"
+ ```json
+ {
+ "components": {
+ "securitySchemes": {
+ "bearerAuth": {
+ "type": "http",
+ "scheme": "bearer"
+ }
}
}
}
- }
- ```
-
+ ```
- Add a `security` field to require authentication.
+ Add a `security` field to require authentication.
-```json
-{
- "security": [
+ ```json
{
- "bearerAuth": []
+ "security": [
+ {
+ "bearerAuth": []
+ }
+ ]
}
- ]
-}
-```
-
+ ```
@@ -168,7 +178,7 @@ For more information on defining and applying authentication, see [Authenticatio
Use the `x-default` extension on a security scheme to pre-fill the authentication field in the API playground. This is useful for providing placeholder values or test credentials that help users get started quickly.
-```json {6}
+```json highlight={6}
{
"components": {
"securitySchemes": {
@@ -211,7 +221,7 @@ Customize your endpoint pages by adding the `x-mint` extension to your OpenAPI s
Override the default metadata for generated API pages by adding `x-mint: metadata` to any operation. You can use any metadata field that would be valid in MDX frontmatter except for `openapi`.
-```json {7-14}
+```json highlight={7-14}
{
"paths": {
"/users": {
@@ -239,7 +249,7 @@ Override the default metadata for generated API pages by adding `x-mint: metadat
You can also control playground display per endpoint using the `playground` and `groups` metadata fields:
-```json {7-11}
+```json highlight={7-11}
{
"paths": {
"/admin/users": {
@@ -264,7 +274,7 @@ This configuration makes the page publicly visible while restricting the interac
Add content before the auto-generated API documentation using `x-mint: content`. The `x-mint: content` extension supports all Mintlify MDX components and formatting.
-```json {6-8}
+```json highlight={6-8}
{
"paths": {
"/users": {
@@ -317,7 +327,7 @@ Annotate parameters in the API reference and playground with custom pill labels
Both fields accept an array of strings. Each string becomes its own pill.
-```json {7-10}
+```json highlight={7-10}
{
"components": {
"schemas": {
@@ -351,13 +361,36 @@ To surface arbitrary OpenAPI spec fields as pills across every parameter without
With this configuration, a property like `{ "type": "string", "nullable": true, "x-internal": "admin" }` renders `nullable` and `admin` pills next to its name. Post pills appear in this order: built-in pills (`read-only`, `write-only`), then `api.params.post` config-driven pills, then per-property `x-mint.post` pills.
+### Collapse nested playground fields
+
+Start nested object fields collapsed in the API playground by adding `x-mint: playground` with `expand: false` to an operation. This keeps the playground compact for endpoints with large or deeply nested request bodies.
+
+```json highlight={6-10}
+{
+ "paths": {
+ "/users": {
+ "post": {
+ "summary": "Create user",
+ "x-mint": {
+ "playground": {
+ "expand": false
+ }
+ }
+ }
+ }
+ }
+}
+```
+
+The top-level request sections, such as Authorization, Path, Query, and Body, always stay expanded. The setting only collapses object fields nested within those sections. Users can expand any collapsed field manually. When `expand` is omitted, all fields start expanded.
+
### Group display names
Set a custom display name for a tag's navigation group using the `x-group` extension on a tag object. By default, Mintlify uses the tag `name` as both the navigation group label and the URL path segment. The `x-group` extension overrides the group label while keeping the tag name for the URL.
This is useful when you want a human-readable group name that differs from the tag used in your API paths.
-```json {4-9}
+```json highlight={4-9}
{
"tags": [
{
@@ -409,7 +442,7 @@ There are two approaches for adding endpoint pages into your documentation:
Generate dedicated API sections by adding an `openapi` field to a navigation element and no other pages. All endpoints in the specification appear in the generated section.
-```json {5}
+```json highlight={5}
"navigation": {
"tabs": [
{
@@ -515,7 +548,7 @@ Child navigation elements inherit their parent's OpenAPI specification unless th
Reference specific endpoints without setting a default OpenAPI specification by including the file path. You can reference endpoints from multiple OpenAPI specifications in the same documentation section.
-```json {5-6}
+```json highlight={5-6}
"navigation": {
"pages": [
"introduction",
diff --git a/es/api-playground/openapi-setup.mdx b/es/api-playground/openapi-setup.mdx
index bf120ab554..2bd55f830f 100644
--- a/es/api-playground/openapi-setup.mdx
+++ b/es/api-playground/openapi-setup.mdx
@@ -378,6 +378,31 @@ Para mostrar campos arbitrarios de la especificación OpenAPI como píldoras en
Con esta configuración, una propiedad como `{ "type": "string", "nullable": true, "x-internal": "admin" }` renderiza las píldoras `nullable` y `admin` junto a su nombre. Las píldoras post aparecen en este orden: píldoras integradas (`read-only`, `write-only`), luego las píldoras impulsadas por la configuración `api.params.post` y, por último, las píldoras `x-mint.post` por propiedad.
+
+ ### Contraer campos anidados del playground
+
+
+Inicia los campos de objetos anidados contraídos en el playground de API agregando `x-mint: playground` con `expand: false` a una operación. Esto mantiene el playground compacto para endpoints con cuerpos de solicitud grandes o muy anidados.
+
+```json {6-10}
+{
+ "paths": {
+ "/users": {
+ "post": {
+ "summary": "Create user",
+ "x-mint": {
+ "playground": {
+ "expand": false
+ }
+ }
+ }
+ }
+ }
+}
+```
+
+Las secciones de solicitud de nivel superior, como Authorization, Path, Query y Body, siempre permanecen expandidas. La configuración solo contrae los campos de objetos anidados dentro de esas secciones. Los usuarios pueden expandir manualmente cualquier campo contraído. Cuando se omite `expand`, todos los campos inician expandidos.
+
### Nombres de visualización de grupo
diff --git a/fr/api-playground/openapi-setup.mdx b/fr/api-playground/openapi-setup.mdx
index e25d1485b3..3dd7a0161d 100644
--- a/fr/api-playground/openapi-setup.mdx
+++ b/fr/api-playground/openapi-setup.mdx
@@ -378,6 +378,31 @@ Pour faire apparaître des champs arbitraires de la spécification OpenAPI sous
Avec cette configuration, une propriété telle que `{ "type": "string", "nullable": true, "x-internal": "admin" }` affiche les pastilles `nullable` et `admin` à côté de son nom. Les pastilles post apparaissent dans cet ordre : pastilles intégrées (`read-only`, `write-only`), puis pastilles définies par la configuration `api.params.post`, puis pastilles `x-mint.post` propres à la propriété.
+
+ ### Réduire les champs imbriqués du playground
+
+
+Affichez les champs d'objets imbriqués réduits par défaut dans le playground d'API en ajoutant `x-mint: playground` avec `expand: false` à une opération. Cela garde le playground compact pour les endpoints avec des corps de requête volumineux ou profondément imbriqués.
+
+```json {6-10}
+{
+ "paths": {
+ "/users": {
+ "post": {
+ "summary": "Create user",
+ "x-mint": {
+ "playground": {
+ "expand": false
+ }
+ }
+ }
+ }
+ }
+}
+```
+
+Les sections de requête de premier niveau, comme Authorization, Path, Query et Body, restent toujours développées. Le paramètre réduit uniquement les champs d'objets imbriqués dans ces sections. Les utilisateurs peuvent développer manuellement tout champ réduit. Lorsque `expand` est omis, tous les champs sont développés par défaut.
+
### Noms d'affichage des groupes
diff --git a/zh/api-playground/openapi-setup.mdx b/zh/api-playground/openapi-setup.mdx
index 94a8532ec0..4acda2ece1 100644
--- a/zh/api-playground/openapi-setup.mdx
+++ b/zh/api-playground/openapi-setup.mdx
@@ -378,6 +378,31 @@ API playground 会使用这些服务器 URL 来确定请求的发送目标。如
通过此配置，类似 `{ "type": "string", "nullable": true, "x-internal": "admin" }` 的属性会在其名称旁渲染 `nullable` 和 `admin` 标签。post 标签按以下顺序显示：内置标签（`read-only`、`write-only`）、由 `api.params.post` 配置驱动的标签，然后是逐属性配置的 `x-mint.post` 标签。
+
+ ### 折叠 playground 中的嵌套字段
+
+
+在操作上添加 `x-mint: playground` 并设置 `expand: false`，使 API playground 中的嵌套对象字段默认折叠。这可以让请求体较大或嵌套较深的端点在 playground 中保持简洁。
+
+```json {6-10}
+{
+ "paths": {
+ "/users": {
+ "post": {
+ "summary": "Create user",
+ "x-mint": {
+ "playground": {
+ "expand": false
+ }
+ }
+ }
+ }
+ }
+}
+```
+
+顶层请求区块（如 Authorization、Path、Query 和 Body）始终保持展开。该设置仅折叠这些区块内嵌套的对象字段。用户可以手动展开任何已折叠的字段。省略 `expand` 时，所有字段默认展开。
+
### 分组显示名称