Componentes
Os três componentes MDC de que é feita uma página de referência gerada.
O tipo openapi escreve páginas Markdown comuns cujo corpo são três componentes
MDC. Estão documentados porque fazem parte da superfície pública — um consumidor
pode substituir qualquer um deles — não porque uma página tenha de ser escrita à
mão.
OpenApiOverview
A página de abertura do documento: info, os servidores, os esquemas de segurança
e a lista de etiquetas com uma contagem cada.
| Prop | Tipo | Notas |
|---|---|---|
info | objecto | title, version, summary, contacto |
servers | array | Cada servidor que o documento declara |
security | objecto | O requisito próprio do documento |
schemes | array | Os esquemas de segurança, por nome |
tags | array | Cada uma com to, uma descrição, uma contagem |
OpenApiOperations
O índice de uma etiqueta: cada operação sob ela como linha, com o método, o caminho, o resumo e se está obsoleta.
| Prop | Tipo | Notas |
|---|---|---|
operations | array | Método, caminho, género, resumo, to |
externalDocs | objecto | O link próprio da etiqueta, quando tem um |
OpenApiOperation
Um endpoint: parâmetros, corpo do pedido, respostas, callbacks e o cliente de ensaio.
| Prop | Tipo | Notas |
|---|---|---|
operation | objecto | A operação compactada |
servers | array | Resolvidos para esta operação |
security | objecto | O requisito próprio da operação, ou nenhum |
securitySchemes | array | Os esquemas que esses requisitos nomeiam |
Substituir um
Como com qualquer outro componente da camada: um ficheiro no mesmo caminho no site consumidor ganha.
app/components/content/OpenApiOperation.vue
As props acima são o contrato. Uma renomeação aqui é uma mudança incompatível da camada.
Sem cabeçalho próprio
Nenhum dos três abre com um <h1>. A casca da documentação desenha o cabeçalho —
migalhas, título, o controlo de copiar ao lado — para toda a página gerada cujo
corpo não abre com um cabeçalho, e uma página de referência quer exactamente isso:
um título e um rasto como qualquer página escrita.