Configuration
L'UI n'a aucune configuration à la compilation : elle résout la spec à afficher entièrement à l'exécution, via une règle avec une seule surcharge possible.
Une règle, une surcharge
| Source | When | Example |
|---|---|---|
GET /api-json | Par défaut : correspond à ce que SwaggerModule.setup() de @nestjs/swagger expose à côté de Swagger UI | https://api.example.com/docs → fetches https://api.example.com/api-json |
?spec=<url> | Paramètre de requête : prend le pas sur la valeur par défaut quand il est présent | https://docs.example.com/?spec=https://api.example.com/api-json |
CORS entre origines différentes
Si l'UI est servie sur une origine différente de l'API, utilise la surcharge ?spec= et assure-toi que la configuration CORS de l'API autorise cette origine à faire un GET sur le document JSON.
Cette question de same-origin revient pour l'exécution des requêtes : voir Try it out pour comment son proxy contourne CORS entièrement, sans toucher à la configuration de l'API elle-même.
Plusieurs specs
Passe specs à DocfyUiModule.setup() pour laisser les utilisateurs basculer entre plusieurs documents OpenAPI sans quitter l'UI, utile quand une seule instance docfy-ui doit couvrir plusieurs services :
DocfyUiModule.setup('/docs', app, {
specs: [
{ name: 'Users service', url: 'https://users.example.com/api-json' },
{ name: 'Orders service', url: 'https://orders.example.com/api-json' },
],
});Chaque url est récupérée côté client exactement comme la spec /api-json par défaut (same-origin ou non, soumise à la politique CORS de cette origine). Un sélecteur apparaît dans la sidebar seulement quand deux specs ou plus sont configurées. Omets entièrement specs et docfy-ui se comporte exactement comme avant, sans sélecteur affiché.