DocfyUiModule.setup(mountPath, app, options?)
Serve o docfy-ui (a UI de documentação AI-first companion desse pacote) no mountPath, o mesmo papel que SwaggerModule.setup() + swagger-ui-express fazem para o Swagger UI cru.
Uso
Funciona tanto com Express (@nestjs/platform-express) quanto com Fastify (@nestjs/platform-fastify). No Fastify, a distribuição dos assets estáticos exige a dependência peer opcional @fastify/static (npm install @fastify/static), o mesmo pacote que o próprio @nestjs/swagger usa para suportar o Swagger UI no 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);Visite /docs: nenhuma configuração adicional necessária, já que docfy-ui busca /api-json same-origin por default.
Options
| Option | Type | Default | Description |
|---|---|---|---|
staticSpecPath | string | nenhum | Path to a pre-built OpenAPI JSON file, served at /api-json instead of the app's live one. |
specs | { name: string; url: string }[] | nenhum | Extra OpenAPI specs to offer in docfy-ui's spec switcher, so one deployed instance can browse more than one service's documentation. |
openApiDocument | { servers?: { url: string }[] } | nenhum | Enables the "Try it out" same-origin proxy — pass the same object you already have from SwaggerModule.createDocument(). See below. |
additionalProxyOrigins | string[] | nenhum | Extra origins the proxy is allowed to forward requests to, beyond what openApiDocument.servers declares. |
guides | { slug, title, content }[] | nenhum | Narrative markdown pages at /guides/:slug, listed in the sidebar. A guide can embed a live, runnable request via a docfy-try fenced block (single line METHOD /path matching an endpoint in the current spec) — renders the endpoint's real request panel inline instead of just linking to its page. |
staticSpecPath (necessário sob webpack: true, se você não usa o plugin do CLI)
O pipeline de metadata em runtime do DocfyModule não consegue aplicar docs files lá, então o /api-json ao vivo vai ficar sem tudo que docs files adicionariam. Ver O plugin do CLI para a correção recomendada e automática. Esta seção cobre a alternativa manual: gere um documento com patch antes:
npx nestjs-docfy patch-spec --spec http://localhost:3000/api-json --out openapi.patched.jsonE sirva ele:
DocfyUiModule.setup('/docs', app, { staticSpecPath: './openapi.patched.json' });Chame isso antes de SwaggerModule.setup(): o Express resolve rotas em ordem de registro, então o documento estático com patch tem precedência sobre o vivo para qualquer request a /api-json. No Fastify, o SwaggerModule.setup() registrar sua própria rota /api-json junto com essa opção causa FST_ERR_DUPLICATED_ROUTE no startup. Ordem de registro não ajuda nesse caso, então aponte o SwaggerModule.setup() para outro jsonDocumentUrl (ou passe { raw: false }) ao combinar com staticSpecPath no Fastify.
Proxy same-origin
Habilita o proxy same-origin do "Try it out" do docfy-ui. Sem essa opção, a execução de request faz um fetch direto do navegador pra API alvo, sujeito à política de CORS dela. Com ela, este módulo registra uma rota same-origin () e o navegador passa a chamar ela: o proxy faz a request real servidor-a-servidor, então CORS nunca entra em jogo. Passe o mesmo documento que você já tem de SwaggerModule.createDocument():
const document = SwaggerModule.createDocument(app, new DocumentBuilder().build());
SwaggerModule.setup('api', app, document);
DocfyUiModule.setup('/docs', app, { openApiDocument: document });A allowlist do proxy é construída só a partir de URLs absolutas no array servers[] do documento, mais o que estiver em additionalProxyOrigins. Deliberadamente não existe fallback implícito de "mesma origem desta request", já que isso teria que vir de um header Host controlado pelo cliente, um vetor clássico de SSRF. Uma request pra qualquer outra origem é rejeitada com e um header de resposta .
Qualquer outra falha no nível do proxy (alvo inacessível, timeout, request malformada) também seta , pra o docfy-ui conseguir distinguir uma falha do proxy de uma resposta 4xx/5xx real vinda da sua API. Essas passam intocadas, com status/headers/body reais.