nestjs-docfy 0.19 — релиз безопасности с несовместимыми изменениями. Читать руководство по миграции →

DocfyUiModule.setup(mountPath, app, options?)

Отдаёт docfy-ui (сопутствующий интерфейс документации с прицелом на ИИ из этого пакета) по адресу mountPath. Ту же роль для обычного Swagger UI играют SwaggerModule.setup() и swagger-ui-express.

Использование

Работает и в приложениях на Express (@nestjs/platform-express), и на Fastify (@nestjs/platform-fastify). Для Fastify отдача статики требует необязательной peer-зависимости @fastify/static (npm install @fastify/static). На этот же пакет опирается и сам @nestjs/swagger в своей поддержке Swagger UI под Fastify.

ts
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);

Откройте /docs. Больше настраивать нечего: docfy-ui по умолчанию запрашивает /api-json с того же origin.

Параметры

OptionTypeDefaultDescription
staticSpecPathstringнетPath to a pre-built OpenAPI JSON file, served at /api-json instead of the app's live one.
specs{ name: string; url: string }[]нет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 }[] }нетEnables the "Try it out" same-origin proxy — pass the same object you already have from SwaggerModule.createDocument(). See below.
additionalProxyOriginsstring[]нетExtra origins the proxy is allowed to forward requests to, beyond what openApiDocument.servers declares.
guides{ slug, title, content }[]нет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.
proxyAuthorize(req) => boolean | Promise<boolean>нетDecides who may use the proxy (false → 403). Nest guards don't run for the proxy route. Required for the proxy in production.
allowProxyInProductionbooleanfalseEnables the proxy in production without proxyAuthorize. Only when the mount path is already protected by something else.
securityHeadersbooleantrueCSP, nosniff, Referrer-Policy and frame headers on the docs UI. false turns them all off (e.g. helmet already sets them).
contentSecurityPolicystringнетReplaces the default Content-Security-Policy value.
cspConnectSrcstring[]нетExtra connect-src origins for the default CSP (e.g. API servers "Try it out" calls directly when the spec has no servers[]).

staticSpecPath (нужен под webpack: true, если вы не используете плагин CLI)

Конвейер метаданных DocfyModule в рантайме не может применить там docs-файлы, поэтому в живом /api-json не будет ничего из того, что эти файлы добавляют. Рекомендуемое автоматическое решение описано в разделе Плагин CLI. Здесь же разбирается ручная альтернатива: подготовить пропатченный документ заранее.

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

И отдать его:

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

Вызывайте это до SwaggerModule.setup(). Express разбирает маршруты в порядке регистрации, поэтому на любой запрос к /api-json пропатченный статический документ окажется важнее живого. На Fastify всё иначе: если SwaggerModule.setup() зарегистрирует рядом собственный маршрут /api-json, приложение упадёт на старте с FST_ERR_DUPLICATED_ROUTE. Порядок регистрации там не спасает, так что вместе с staticSpecPath на Fastify направьте SwaggerModule.setup() на другой jsonDocumentUrl либо передайте { raw: false }.

Прокси на том же origin

Включает прокси на том же origin для режима «Try it out» в docfy-ui. Без него браузер отправляет запрос прямо в целевой API и подчиняется его политике CORS. С ним модуль регистрирует маршрут на своём origin (), браузер обращается уже туда, а настоящий запрос прокси делает сам, сервер к серверу, поэтому CORS вообще не при делах. Передайте тот же документ, который у вас уже есть из SwaggerModule.createDocument():

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

Белый список прокси строится только из абсолютных URL в массиве servers[] документа плюс всего, что перечислено в additionalProxyOrigins. Неявного запасного варианта «тот же origin, что и у запроса» здесь нет намеренно: его пришлось бы выводить из заголовка Host, которым управляет клиент, а это классический вектор SSRF. Запрос к любому другому origin отклоняется с и заголовком ответа .

Любой другой сбой на уровне прокси (цель недоступна, таймаут, кривой запрос) тоже проставляет , чтобы docfy-ui отличал падение прокси от настоящего ответа 4xx/5xx вашего API. Такие ответы проходят насквозь нетронутыми, со своим статусом, заголовками и телом.

При NODE_ENV=production прокси отключён, пока вы не зададите proxyAuthorize — хук, который решает, кому можно им пользоваться: guards Nest для этого маршрута никогда не выполняются. См. Безопасность и миграция.

ts
DocfyUiModule.setup('/docs', app, {
  openApiDocument: document,
  proxyAuthorize: async (req) => (await currentUser(req))?.roles.includes('developer') ?? false,
});