Ajouter votre référence API

0:00 / 0:13

Indiquer le contrat
Un chemin, ou une liste — chaque entrée devient un service distinct.
specistry.config.ts
```
openapi: "./openapi.yaml",
```
La placer dans la barre latérale
Sans navigation, les pages viennent d’abord, puis la référence API.
specistry.config.ts
```
navigation: [
  "quickstart",
  { api: true, label: "Référence API" },
],
```
Y faire des liens depuis les guides
Les liens vers l’API sont vérifiés contre le contrat au moment du build.
docs/quickstart.md
```
Créez-en une avec [Créer une boîte](/api/inboxes/create-inbox).
Voir la [réponse 201](/api/inboxes/create-inbox#response-201).
```

Comment sont formées les URL

La référence vit sous /api
Les groupes sont les tags — slug du nom du tag, dans l’ordre déclaré
Le slug d’une opération est son operationId en kebab-case, ou méthode-chemin à défaut
En cas de collision : -2, -3 selon l’ordre canonique
Les opérations sans tag vont dans un groupe operations, placé en dernier

AstuceDes URL stables

Donnez un operationId à chaque opération : renommer un chemin ne changera plus l’URL de la documentation.

Plusieurs contrats

specistry.config.ts

openapi: [
  "./contracts/identity.yaml",
  "./contracts/payments.yaml",
],

Deux contrats ne sont jamais fusionnés, même si leurs chemins se ressemblent. Les $ref locales sont résolues dans le projet ; les références distantes sont désactivées.

Cas particuliers

$ref distante

Références distantes désactivées

✕ ÉCHOUE

openapi.yaml

$ref: "https://schemas.acme.dev/inbox.yaml"

✓ CORRECTION

openapi.yaml

$ref: "./schemas/inbox.yaml"

Le build doit être reproductible, même hors ligne.

Lien vers une opération inexistante

CONTENT_LINK_TARGET_MISSING

✕ ÉCHOUE

docs/quickstart.md

[Créer](/api/inboxes/create)

✓ CORRECTION

docs/quickstart.md

[Créer](/api/inboxes/create-inbox)

Le slug vient de l’operationId `createInbox` → `create-inbox`.