openapi a cualquier elemento de navegación de tu docs.json, como una pestaña, un anchor o un grupo, para generar páginas de endpoints a partir de una especificación. El campo openapi acepta una ruta en tu repositorio de documentación o la URL de una especificación alojada.
Puedes agregar endpoints de dos maneras:
- Generar una sección a partir de una especificación completa. Cada endpoint obtiene una página, agrupada por tag. Usa esta opción para la mayoría de las referencias de API.
- Enumerar endpoints específicos. Solo los endpoints que enumeras obtienen páginas, en el orden en que los enumeras, junto a tus otras páginas.
openapi a un elemento de navegación sin pages. Cada endpoint de la especificación obtiene una página en ese elemento.
docs.json
name de su tag. Para mostrar una etiqueta distinta, agrega x-group al tag. La URL sigue usando el name del tag.
x-group, Mintlify usa su extensión x-displayName como etiqueta, así que las especificaciones que ya usan x-displayName no necesitan cambios. Si un tag tiene ambas, prevalece x-group.
En los documentos OpenAPI 3.2, los tags pueden declarar los campos parent, kind y summary. Mintlify los usa para crear grupos anidados. Los documentos OpenAPI 3.0 y 3.1 mantienen un grupo plano por tag.
parent: anida el grupo del tag dentro del grupo del tag padre.summary: define la etiqueta del grupo. Si un tag también tienex-groupox-displayName, prevalece la extensión, primerox-group.kind: controla cómo usa Mintlify el tag.navo sinkind: crea un grupo de navegación.badge: muestra elsummarydel tag, o sunamesi no haysummary, como una píldora junto al endpoint en la barra lateral. Los tags de tipo badge no crean grupos.- Cualquier otro valor, como
audience: no crea ni un grupo ni una píldora.
kind: nav. Si no hay ninguno, Mintlify usa el primer tag declarado sin kind y, después, el primer tag que no está declarado en tags. Para definir una píldora distinta para un endpoint, usa tag en x-mint.metadata, que tiene prioridad sobre los tags de tipo badge.
La validación falla si dos tags comparten nombre, si un parent hace referencia a un tag que no existe o si las referencias parent forman un ciclo.
Para elegir qué endpoints obtienen páginas y dónde aparecen, configura un openapi predeterminado en un elemento de navegación y enumera los endpoints en su pages como METHOD /path. Puedes mezclar endpoints con otras páginas.
docs.json
openapi:
docs.json
docs.json
pages que no coincida con una operación como una ruta de archivo. Los métodos HTTP deben estar en mayúsculas.
Para generar páginas a partir de más de una especificación, coloca cada especificación en su propio elemento de navegación y asigna a cada una su propio directory. Si configuras openapi como un array, Mintlify solo genera páginas a partir de la primera especificación del array.
docs.json
directory define la carpeta en la URL de cada página generada. Si dos especificaciones comparten un directory y producen la misma URL de página, una página reemplaza a la otra sin avisar. Consulta URLs y títulos de endpoints.
Mintlify no lee la extensión x-tagGroups. Para una especificación con muchos tags, elige un enfoque:
- Una especificación por sección. Divide la especificación en un archivo por área de producto, o usa overlays para eliminar las operaciones que no pertenecen a cada sección, y después asigna a cada una su propia sección.
- Jerarquías de tags. Actualiza a OpenAPI 3.2 y anida tags dentro de tags padre.
- Enumerar endpoints. Enumera cada endpoint en tu
docs.jsonen los grupos que quieras. Esto te da control total, pero debes agregar tú mismo los nuevos endpoints adocs.json.
x-hidden o x-excluded a una operación o un webhook para mantenerlo fuera de tu navegación generada:
x-hidden: true: el endpoint obtiene una página, pero la página no aparece en la navegación. Cualquier persona con la URL puede abrirla. Úsalo para endpoints que enlazas desde otras páginas o compartes con usuarios específicos.x-excluded: true: el endpoint no obtiene una página. Úsalo para endpoints internos o que todavía no están listos para documentarse.
x-excluded solo elimina la página. Si los visitantes pueden acceder a tu archivo de especificación, los endpoints excluidos siguen estando en él.
Para mostrar endpoints solo a grupos de usuarios específicos, agrega x-mint.groups a la operación. Consulta Filtrado de contenido de OpenAPI.