Composants
Les trois composants MDC dont est faite une page de référence générée.
Le type openapi écrit des pages Markdown ordinaires dont le corps est fait de
trois composants MDC. Ils sont documentés parce qu’ils font partie de la surface
publique — un consommateur peut surcharger n’importe lequel — non parce qu’une
page devrait être écrite à la main.
OpenApiOverview
La page de garde du document : info, les serveurs, les schémas de sécurité et la
liste des étiquettes avec un décompte chacune.
| Prop | Type | Remarques |
|---|---|---|
info | objet | title, version, summary, contact |
servers | tableau | Chaque serveur que le document déclare |
security | objet | L’exigence propre du document |
schemes | tableau | Les schémas de sécurité, par nom |
tags | tableau | Chacune avec un to, une description, un décompte |
OpenApiOperations
L’index d’une étiquette : chaque opération dessous en ligne, avec sa méthode, son chemin, son résumé et si elle est dépréciée.
| Prop | Type | Remarques |
|---|---|---|
operations | tableau | Méthode, chemin, genre, résumé, to |
externalDocs | objet | Le lien propre de l’étiquette, s’il existe |
OpenApiOperation
Un endpoint : paramètres, corps de requête, réponses, callbacks et le client d’essai.
| Prop | Type | Remarques |
|---|---|---|
operation | objet | L’opération compactée |
servers | tableau | Résolus pour cette opération |
security | objet | L’exigence propre de l’opération, ou aucune |
securitySchemes | tableau | Les schémas que ces exigences nomment |
En surcharger un
Comme pour tout autre composant livré par la couche : un fichier au même chemin dans le site consommateur gagne.
app/components/content/OpenApiOperation.vue
Les props ci-dessus sont le contrat. Un renommage ici est un changement cassant de la couche.
Pas de titre à eux
Aucun des trois n’ouvre sur un <h1>. La coque de la documentation dessine
l’en-tête — fil d’Ariane, titre, le contrôle de copie à côté — pour toute page
générée dont le corps n’ouvre sur aucun titre, et une page de référence veut
exactement cela : un titre et une trace comme toute page écrite.