Declarar la sección

Una referencia es una sección generada: una fuente nombra un artefacto y el tipo que lo lee, y las páginas se siguen de ahí.

export default defineAppConfig({
  duxt: {
    sources: [
      {
        path: 'docs',
        generated: [
          {
            type: 'openapi',
            path: 'openapi.yaml',
            label: 'API'
          }
        ]
      }
    ]
  }
})

Los campos que toma una declaración son los mismos para cualquier tipo y están en Fuentes. openapi no nombra ninguna opción propia; lo que sí responde está debajo.

#Qué construye

/api                      la visión general, desde `info`
/api/<tag>                una página por etiqueta
/api/<tag>/<operation>    una página por operación, con el cliente

Una operación sin etiqueta cae en un grupo por defecto, y los webhooks de 3.1 en uno propio — un webhook es el mismo objeto bajo un nombre en lugar de una URL, así que se renderiza por la misma página y dice cuál es.

#Versionado

Por versión. La descripción de una API pertenece a la release que describe: v1 y v2 tienen endpoints distintos, y a un lector en v1 que pregunta qué significa un campo no se le puede mostrar la respuesta de v2. Cada colección de versión lleva el documento en su propia ref, y el selector de versiones funciona sobre la referencia igual que sobre la prosa.

Es lo contrario de lo que hace el tipo changelog, y la razón de que el versionado sea una política del tipo y no una regla de la capa.

#Localización

Por idioma, donde ese idioma trae un documento propio. Una descripción es prosa escrita tanto como estructura — resúmenes, descripciones de campos, significados de las respuestas — así que una traducida es un artefacto real y no el mismo archivo con otra etiqueta.

{
  type: 'openapi',
  path: 'openapi.yaml',
  label: 'API',
  locales: { de: 'openapi.de.yaml' }
}

Un idioma ausente del mapa no construye ninguna colección, y la cadena de respaldo existente le sirve la referencia del idioma por defecto, con el aviso de traducción diciéndolo — ver Localización. Lo que sigue traducido en cualquier caso son las etiquetas propias de la capa — las cabeceras de tabla, «Request», «Response», los nombres de estado — porque esas pertenecen al tema y no al documento.

#Cuando el documento no se puede leer

La compilación falla, y dice qué sección y por qué. Es deliberado: una referencia que se convirtió en silencio en una sección vacía es una referencia cuya desaparición nadie nota.