Documentación de referencia de OpenAPI

docStatic utiliza docusaurus-plugin-openapi-docs para generar documentación de referencia de API a partir de una especificación OpenAPI. El plugin lee un archivo de especificación y escribe un conjunto de archivos MDX en su árbol docs/ que Docusaurus construye como páginas normales.

Configuración

Las fuentes de API se configuran en config/docusaurus/index.json bajo el array openapi.apis. Cada entrada especifica un nombre, la ruta al archivo de especificación, el directorio de salida y opciones de agrupación opcionales:

{
  "openapi": {
    "apis": [
      {
        "name": "petstore",
        "specPath": "openapi/petstore.yaml",
        "outputDir": "docs/api/petstore",
        "groupPathsBy": "tag",
        "categoryLinkSource": "tag"
      }
    ]
  }
}

Ejecute la generación con:

npm run gen-api-docs

Para eliminar los archivos generados:

npm run clean-api-docs

Páginas de etiquetas

Cuando groupPathsBy y categoryLinkSource están ambos configurados como "tag", el plugin crea una página de índice de categoría para cada etiqueta de OpenAPI (p. ej. store.tag.mdx). Por defecto, estos archivos contienen un bloque de texto estándar que importa DocCardList y useCurrentSidebarCategory — ambos redundantes en docStatic porque DocCardList ya está registrado globalmente como componente MDX, y el componente resuelve automáticamente los elementos de la categoría actual cuando se llama sin props.

docStatic configura el plugin con una plantilla de etiqueta personalizada que produce en su lugar la forma simplificada:

<DocCardList />

La plantilla se encuentra en config/docusaurus/openapi-tag-template.md y se conecta mediante la opción tagTemplate en docusaurus.config.ts.

Edición de archivos de etiquetas generados

El plugin solo crea un archivo de etiqueta si no existe uno — nunca sobreescribirá un archivo que haya editado. Esto significa que puede personalizar libremente el texto de descripción en una página de etiqueta y sobrevivirá a las ejecuciones posteriores de gen-api-docs. Solo las etiquetas recién introducidas tendrán un archivo escrito para ellas, y esas usarán la plantilla personalizada.