DocfyUiModule.setup(mountPath, app, options?)

Usage

Fonctionne aussi bien sur Express (@nestjs/platform-express) que sur Fastify (@nestjs/platform-fastify). Sur Fastify, servir les assets statiques nécessite la dépendance peer optionnelle @fastify/static (npm install @fastify/static), le même package dont dépend déjà @nestjs/swagger pour son propre support de Swagger UI sur Fastify.

import { NestFactory } from '@nestjs/core';
import { SwaggerModule, DocumentBuilder } from '@nestjs/swagger';
import { DocfyUiModule } from 'nestjs-docfy';

const app = await NestFactory.create(AppModule);

DocfyUiModule.setup('/docs', app); // before SwaggerModule.setup; see staticSpecPath below

const document = SwaggerModule.createDocument(app, new DocumentBuilder().build());
SwaggerModule.setup('api', app, document); // exposes /api-json, which docfy-ui fetches by default

await app.listen(3000);

Va sur /docs : aucune configuration supplémentaire n'est nécessaire, puisque docfy-ui récupère /api-json en same-origin par défaut.

Options

staticSpecPath (nécessaire sous webpack: true, si tu n'utilises pas le plugin CLI)

Le pipeline de métadonnées runtime de DocfyModule ne peut pas appliquer les fichiers docs à cet endroit, donc le /api-json en direct manquera tout ce que les fichiers docs auraient ajouté. Voir Le plugin CLI pour le correctif automatique recommandé. Cette section couvre l'alternative manuelle : générer un document patché au préalable :

npx nestjs-docfy patch-spec --spec http://localhost:3000/api-json --out openapi.patched.json

Et le servir :

DocfyUiModule.setup('/docs', app, { staticSpecPath: './openapi.patched.json' });

Appelle ceci avant SwaggerModule.setup() : Express résout les routes dans l'ordre d'enregistrement, donc le document statique patché prend le pas sur celui en direct pour toute requête vers /api-json. Sur Fastify, SwaggerModule.setup() qui enregistre sa propre route /api-json en plus de celle-ci lève FST_ERR_DUPLICATED_ROUTE au démarrage. L'ordre d'enregistrement n'aide pas dans ce cas, donc pointe SwaggerModule.setup() vers un jsonDocumentUrl différent (ou passe { raw: false }) quand tu le combines avec staticSpecPath sur Fastify.

Proxy same-origin

Active le proxy same-origin « Try it out » de docfy-ui. Sans lui, l'exécution de la requête fait un fetch direct du navigateur vers l'API cible, soumis à la politique CORS propre de cette API. Avec lui, ce module enregistre une route same-origin () et le navigateur appelle celle-ci à la place : le proxy fait la vraie requête serveur à serveur, donc CORS ne s'applique jamais. Passe le même document que tu as déjà depuis SwaggerModule.createDocument() :

const document = SwaggerModule.createDocument(app, new DocumentBuilder().build());
SwaggerModule.setup('api', app, document);
DocfyUiModule.setup('/docs', app, { openApiDocument: document });

La liste blanche du proxy est construite uniquement à partir des URLs absolues du tableau servers[] du document, plus tout ce qui figure dans additionalProxyOrigins. Il n'y a délibérément pas de repli implicite « même origine que cette requête », puisque ça devrait être dérivé d'un en-tête Host contrôlé par le client, un vecteur SSRF classique. Une requête pour toute autre origine est rejetée avec et un en-tête de réponse .

Tout autre échec côté proxy (cible injoignable, timeout, requête malformée) fixe aussi , pour que docfy-ui puisse distinguer un échec de proxy d'une vraie réponse 4xx/5xx venant de ton API. Celles-ci passent inchangées, avec leur vrai statut, leurs vrais en-têtes et leur vrai corps.