api.playground en tu docs.json.
Agrega un campo servers a tu especificación OpenAPI con la URL base de tu API. El playground añade la ruta de cada endpoint, como /users/{id}, a esta URL.
simple.
Si tu API sirve algunos endpoints desde una URL distinta, sobrescribe el campo servers para una ruta u operación. Para obtener más información sobre el campo servers, consulta API server and base path en la documentación de OpenAPI.
Define cómo se autentican los lectores con los campos securitySchemes y security de tu especificación OpenAPI. El playground agrega un campo de entrada para cada esquema, para que los lectores puedan introducir sus credenciales antes de enviar una solicitud.
1
Define tu método de autenticación.
Agrega un campo
securitySchemes. Este ejemplo define una autenticación bearer.2
Aplica la autenticación a tus endpoints.
Agrega un campo
security para exigir el esquema.- API keys: para claves en encabezados, parámetros de consulta o cookies.
- Bearer: para tokens JWT u OAuth.
- Basic: para un nombre de usuario y una contraseña.
security para una operación. Para obtener más información, consulta Authentication en la documentación de OpenAPI.
El playground genera una descripción para el campo de autorización según el tipo de esquema de seguridad. Para reemplazarla con tu propio texto, como dónde encuentran los lectores su clave, agrega una description al esquema de seguridad. La descripción admite Markdown y se aplica a todos los endpoints que usan el esquema.
x-default a un esquema de seguridad para rellenar previamente su campo en el playground, por ejemplo con un marcador de posición o una credencial de prueba. x-default funciona en esquemas apiKey y http bearer.
security de una operación enumera scopes, la página del endpoint los muestra en una sección Scopes después de la sección de autorización. El playground también los enumera debajo del campo de la opción de autorización seleccionada.
security, para que los lectores los vean sin importar qué opción de autorización seleccionen. En este ejemplo, users:read aparece aunque apiToken sea la primera opción.
- Las descripciones de los scopes provienen del mapa
scopesen losflowsdel esquema OAuth 2.0. - En OpenAPI 3.1, las listas de roles en los requisitos
apiKeyyhttp, como{ "apiKey": ["admin"] }, aparecen en la misma sección. - Si más de un esquema requiere scopes, una etiqueta junto a cada scope muestra el nombre de su esquema.
api.playground.display en tu docs.json para controlar lo que aparece en cada página de endpoint:
interactive(predeterminado): el playground completo.simple: un endpoint copiable sin playground.none: sin playground.auth: el playground completo para los lectores con sesión iniciada y nada para los demás. Consulta Mostrar el playground solo a los lectores con sesión iniciada.
docs.json
playground en el frontmatter de la página, o en x-mint.metadata para una página generada.
auth para mantener pública tu referencia de API y permitir que solo los lectores con sesión iniciada envíen solicitudes. El modo auth requiere autenticación en tu sitio.
Para limitar el playground a grupos de usuarios específicos, agrega groups al frontmatter de la página. Si la página no tiene groups, todos los lectores con sesión iniciada ven el playground.
admin o developer ven el playground.
Para las páginas generadas, configura los mismos campos en x-mint.metadata:
api.playground.proxy como false para enviar las solicitudes directamente desde el navegador del lector a tu API. Hazlo si tu API requiere encabezados que el proxy no puede reenviar, o si las solicitudes deben provenir del navegador del lector, por ejemplo, para la autenticación basada en cookies. En ese caso, tu API debe permitir solicitudes cross-origin desde tu dominio de documentación con CORS.
Para enviar cookies, encabezados de autorización y certificados de cliente TLS con las solicitudes directas, configura también credentials como true.
docs.json
POST a la ruta /_mintlify/api/request. Con el proxy de Mintlify activado, el playground envía cada solicitud como un POST a esa ruta. Si tu proxy inverso no puede permitir solicitudes POST, configura proxy como false.
Para completar los campos de la solicitud con los valores de ejemplo de tu especificación OpenAPI, configura api.examples.prefill como true en tu docs.json.
docs.json
default en el esquema, agrega x-default a la propiedad. x-default en una propiedad solo tiene efecto cuando prefill es true. x-default en un esquema de seguridad siempre tiene efecto.
Para ver la lista completa de configuraciones del playground, consulta Configuración de API.