Declarar a secção

Uma referência é uma secção gerada: uma fonte nomeia um artefacto e o tipo que o lê, e as páginas seguem daí.

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

Os campos que uma declaração aceita são os mesmos para qualquer tipo e estão em Fontes. openapi não nomeia nenhuma opção própria; o que responde está abaixo.

#O que constrói

/api                      a visão geral, a partir de `info`
/api/<tag>                uma página por etiqueta
/api/<tag>/<operation>    uma página por operação, com o cliente

Uma operação sem etiqueta cai num grupo por omissão, e os webhooks de 3.1 num grupo próprio — um webhook é o mesmo objecto sob um nome em vez de um URL, por isso renderiza pela mesma página e diz o que é.

#Versionamento

Por versão. A descrição de uma API pertence à release que descreve: v1 e v2 têm endpoints diferentes, e a um leitor em v1 que pergunta o que significa um campo não pode ser mostrada a resposta da v2. Cada coleção de versão leva o documento na sua própria ref, e o selector de versões actua sobre a referência tal como actua sobre a prosa.

É o contrário do que faz o tipo changelog, e a razão por que o versionamento é uma política do tipo e não uma regra da camada.

#Localização

Por idioma, onde esse idioma traz um documento próprio. Uma descrição é prosa escrita tanto como estrutura — resumos, descrições de campos, significados das respostas — por isso uma traduzida é um artefacto real e não o mesmo ficheiro com outra etiqueta.

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

Um idioma ausente do mapa não constrói coleção alguma, e a cadeia de recurso existente serve-lhe a referência do idioma por omissão, com o banner de tradução a dizê-lo — ver Localização. O que fica traduzido em qualquer caso são as etiquetas da própria camada — os cabeçalhos de tabela, «Request», «Response», os nomes de estado — porque essas pertencem ao tema e não ao documento.

#Quando o documento não pode ser lido

A build falha, e diz qual secção e porquê. É deliberado: uma referência que se tornou em silêncio uma secção vazia é uma referência cujo desaparecimento ninguém nota.