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.
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.
Параметры
| Option | Type | Default | Description |
|---|---|---|---|
staticSpecPath | string | нет | 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. |
additionalProxyOrigins | string[] | нет | 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. |
staticSpecPath (нужен под webpack: true, если вы не используете плагин CLI)
Конвейер метаданных DocfyModule в рантайме не может применить там docs-файлы, поэтому в живом /api-json не будет ничего из того, что эти файлы добавляют. Рекомендуемое автоматическое решение описано в разделе Плагин CLI. Здесь же разбирается ручная альтернатива: подготовить пропатченный документ заранее.
npx nestjs-docfy patch-spec --spec http://localhost:3000/api-json --out openapi.patched.jsonИ отдать его:
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():
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. Такие ответы проходят насквозь нетронутыми, со своим статусом, заголовками и телом.