Więcej niż zwykła
dokumentacja Swagger.
nestjs-docfy oddziela dokumentację Swagger/OpenAPI od logiki kontrolera przy pomocy konwencji nazewnictwa pliku towarzyszącego, dokładnie tak, jak Nest robi to już z *.controller.spec.ts.
npm install nestjs-docfy
# peer deps
npm install @nestjs/common @nestjs/swagger reflect-metadatadocfy-ui: referencyjny viewer AI-first
Specyfikacja OpenAPI, którą składa nestjs-docfy, to też to, co renderuje docfy-ui, bez osobnej konfiguracji i z tym samym źródłem prawdy.
- Copy for AI: deterministyczne, gotowe dla LLM podsumowanie endpointu, a nie surowy zrzut JSON-a z $ref
- Wyszukiwanie ⌘K po każdym endpoincie, natychmiast
- Pełne szczegóły żądania/odpowiedzi dla każdego endpointu, generowane wprost ze specyfikacji
Stworzone dla agentów AI, nie tylko dla ludzi
docfy-mcp udostępnia twoją specyfikację OpenAPI jako narzędzia MCP, więc Claude, Cursor lub dowolny agent kompatybilny z MCP odpytuje twoje API bezpośrednio, bez wklejania JSON-a do prompta.
- list_endpoints / get_endpoint: przeglądaj i sprawdzaj dowolną operację, w tym samym znormalizowanym kształcie, który renderuje docfy-ui
- lint_spec: sygnalizuje brakujące summaries, opisy, tagi i odpowiedzi błędów zanim trafią na produkcję
- diff_specs: porównuje dwa dokumenty OpenAPI i oznacza zmiany łamiące kontrakt vs. informacyjne
- contract_test: waliduje rzeczywistą odpowiedź względem zadeklarowanego schematu, bezpośrednio z wywołań narzędzi agenta
- Zero konfiguracji wobec działającego serwera NestJS, albo wskaż statyczny plik specyfikacji
{
"mcpServers": {
"docfy": {
"command": "npx",
"args": ["-y", "docfy-mcp", "--url", "http://localhost:3000/docs-json"]
}
}
}Jak to wygląda w praktyce
Przed: kontroler zagrzebany w dekoratorach. Po: same trasy, z dokumentacją mieszkającą obok, w pliku towarzyszącym.
@WithDocs()
@Controller('users')
export class UsersController {
constructor(private readonly users: UsersService) {}
@Get(':id')
findOne(@Param('id') id: string) {
return this.users.findOne(id);
}
}import { docs } from 'nestjs-docfy';
import { ApiTags, ApiOperation, ApiResponse } from '@nestjs/swagger';
import { UsersController } from './users.controller';
docs(UsersController, {
classDecorators: [ApiTags('users')],
methods: {
findOne: [
ApiOperation({ summary: 'Get user by id' }),
ApiResponse({ status: 200, description: 'OK', type: UserDto }),
ApiResponse({ status: 404, description: 'User not found' }),
],
},
});Bez monkey-patchingu, bez proxy w runtime
Wystarczy właściwy moment i metadane Reflect.
Napisz plik towarzyszący
users.controller.docs.ts wywołuje docs(UsersController, { ... }), zwykłe dekoratory Swaggera, tylko w innym pliku.
Wykrywany przy starcie
DocfyModule.forRoot() znajduje go przez konwencję nazewnictwa i zapisuje metadane Reflect na metodach kontrolera, zanim uruchomi się SwaggerModule.createDocument().
Identyczny wynik OpenAPI
SwaggerModule widzi dokładnie te same metadane, które widziałby, gdyby dekoratory były zapisane inline w kontrolerze.
To nie plugin do Swaggera. To cały toolchain.
Większość narzędzi kończy się na dekoratorach. nestjs-docfy dostarcza CLI, viewer i integrację z AI, których twój zespół naprawdę potrzebuje, by dokumentacja była wiarygodna.
CLI, które blokuje twoje CI
generate, check, coverage --min, lint i patch-spec zatrzymują build w momencie, gdy dokumentacja odbiega od kodu, a nie dopiero miesiące później.
Zerowy koszt w runtime, jeśli chcesz
Wtyczka webpack CLI liczy wszystko w czasie builda; nic nie działa per-request na produkcji.
docfy-ui w zestawie, nie sprzedawane osobno
Pełny viewer referencyjny AI-first jest częścią biblioteki, bez dodatkowego konta i bez osobnego planu.
Agenci jako obywatele pierwszej kategorii
docfy-mcp udostępnia tę samą specyfikację Claude, Cursorowi i dowolnemu klientowi MCP: twoje API staje się przeszukiwalne, nie tylko czytelne.
Działa z układem NestJS, który już masz
Proste projekty, workspace'y Nx i monorepo Nest CLI są wykrywane automatycznie, bez żadnego pliku konfiguracyjnego do ręcznego pisania.
Jedna komenda od zera do pełnej konfiguracji
nestjs-docfy init podłącza moduł, dekoruje każdy kontroler i generuje dokumentację, wszystko za jednym razem.