DocfyUiModule.setup(mountPath, app, options?)

Serwuje docfy-ui (towarzyszący interfejs dokumentacji AI-first tego pakietu) pod mountPath, pełniąc tę samą rolę co SwaggerModule.setup() + swagger-ui-express dla surowego Swagger UI.

Użycie

Działa zarówno na aplikacjach Express (@nestjs/platform-express), jak i Fastify (@nestjs/platform-fastify). Na Fastify serwowanie zasobów statycznych wymaga opcjonalnej zależności peer @fastify/static (npm install @fastify/static), tego samego pakietu, na którym opiera się @nestjs/swagger przy obsłudze Swagger UI na 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);

Odwiedź /docs: żadna dodatkowa konfiguracja nie jest potrzebna, ponieważ docfy-ui domyślnie pobiera /api-json z tego samego origin.

Opcje

OptionTypeDefaultDescription
staticSpecPathstringbrakPath to a pre-built OpenAPI JSON file, served at /api-json instead of the app's live one.
specs{ name: string; url: string }[]brakExtra 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 }[] }brakEnables the "Try it out" same-origin proxy — pass the same object you already have from SwaggerModule.createDocument(). See below.
additionalProxyOriginsstring[]brakExtra origins the proxy is allowed to forward requests to, beyond what openApiDocument.servers declares.

staticSpecPath (potrzebne przy webpack: true, jeśli nie używasz pluginu CLI)

Pipeline runtime'owy DocfyModule nie może tam zastosować plików docs, więc żywy /api-json będzie pozbawiony wszystkiego, co dodałyby te pliki. Rekomendowane, automatyczne rozwiązanie opisuje The CLI plugin. Ta sekcja pokazuje ręczną alternatywę: wygeneruj wcześniej załatany dokument:

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

I serwuj go:

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

Wywołaj to przed SwaggerModule.setup(): Express rozwiązuje trasy w kolejności rejestracji, więc załatany statyczny dokument ma pierwszeństwo przed żywym dla każdego żądania do /api-json. Na Fastify rejestracja własnej trasy /api-json przez SwaggerModule.setup() obok tego rzuca zamiast tego FST_ERR_DUPLICATED_ROUTE przy starcie. Kolejność rejestracji nic tu nie zmienia, więc skieruj SwaggerModule.setup() na inny jsonDocumentUrl (albo przekaż { raw: false }), gdy łączysz go z staticSpecPath na Fastify.

Proxy w ramach tego samego origin

Włącza proxy „Try it out” w docfy-ui, działające w ramach tego samego origin. Bez tego wykonanie żądania to bezpośrednie pobranie z przeglądarki do docelowego API, podlegające jego własnej polityce CORS. Z tym modułem rejestrowana jest trasa w ramach tego samego origin () i przeglądarka wywołuje ją zamiast tego: proxy wykonuje prawdziwe żądanie serwer-serwer, więc CORS nigdy się nie stosuje. Przekaż ten sam dokument, który masz już z SwaggerModule.createDocument():

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

Lista dozwolonych adresów proxy jest budowana wyłącznie z bezwzględnych URL-i w tablicy servers[] dokumentu, plus wszystko z additionalProxyOrigins. Celowo nie ma niejawnego fallbacku „ten sam origin co to żądanie”, bo musiałby być wyznaczany z kontrolowanego przez klienta nagłówka Host, klasycznego wektora SSRF. Żądanie do dowolnego innego origin jest odrzucane z odpowiedzią i nagłówkiem .

Każda inna awaria na poziomie proxy (cel nieosiągalny, timeout, źle sformułowane żądanie) też ustawia , dzięki czemu docfy-ui potrafi odróżnić awarię proxy od prawdziwej odpowiedzi 4xx/5xx z Twojego API. Te przechodzą bez zmian, z prawdziwym statusem, nagłówkami i treścią.