Uma referência é uma [secção gerada](/concepts/generated-sections): uma fonte
nomeia um artefacto e o tipo que o lê, e as páginas seguem daí.

```ts
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](/reference/sources). `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.

```ts
{
  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](/concepts/localisation). 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.