Componentes
Los tres componentes MDC de los que está hecha una página de referencia generada.
El tipo openapi escribe páginas Markdown ordinarias cuyo cuerpo son tres
componentes MDC. Están documentados porque forman parte de la superficie pública
— un consumidor puede sobrescribir cualquiera — no porque haya que escribir una
página a mano.
OpenApiOverview
La portada del documento: info, los servidores, los esquemas de seguridad y la
lista de etiquetas con un recuento cada una.
| Prop | Tipo | Notas |
|---|---|---|
info | objeto | title, version, summary, contacto |
servers | array | Cada servidor que declara el documento |
security | objeto | El requisito propio del documento |
schemes | array | Los esquemas de seguridad, por nombre |
tags | array | Cada uno con to, una descripción, un recuento |
OpenApiOperations
El índice de una etiqueta: cada operación bajo ella como fila, con su método, ruta, resumen y si está obsoleta.
| Prop | Tipo | Notas |
|---|---|---|
operations | array | Método, ruta, clase, resumen, to |
externalDocs | objeto | El enlace propio de la etiqueta, si tiene |
OpenApiOperation
Un endpoint: parámetros, cuerpo de la petición, respuestas, callbacks y el cliente de pruebas.
| Prop | Tipo | Notas |
|---|---|---|
operation | objeto | La operación compactada |
servers | array | Resueltos para esta operación |
security | objeto | El requisito propio de la operación, o ninguno |
securitySchemes | array | Los esquemas que nombran esos requisitos |
Sobrescribir uno
Igual que con cualquier otro componente de la capa: un archivo en la misma ruta del sitio consumidor gana.
app/components/content/OpenApiOperation.vue
Las props de arriba son el contrato. Un renombrado aquí es un cambio incompatible de la capa.
Sin encabezado propio
Ninguno de los tres abre con un <h1>. El armazón de la documentación dibuja la
cabecera — migas, título, el control de copia al lado — para toda página generada
cuyo cuerpo no abre con un encabezado, y una página de referencia quiere
exactamente eso: un título y un rastro como cualquier página escrita.