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.

Zaczynamy Zobacz na GitHubie Zobacz na npm

Installation

npm install nestjs-docfy
# peer deps
npm install @nestjs/common @nestjs/swagger reflect-metadata

Ostatnie wydanie v0.13.0Licencja MIT

Plik towarzyszący z konwencji

users.controller.ts → users.controller.docs.ts. Ten sam wzorzec, którego Nest już używa dla *.controller.spec.ts.

CLI z bramkami CI

check, coverage --min, lint i patch-spec. Przerywa build, gdy brakuje dokumentacji.

Automatyczne wnioskowanie typów

Interfejsy, class-validator i @HttpCode() stają się schematem OpenAPI bez dodatkowych dekoratorów.

Docfy UI AI-first

Referencyjny interfejs z przyciskiem Copy for AI przy każdym endpoincie, idealny do wklejania w LLM-y.

docfy-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

docfy-ui detalhe de endpoint com Copy for AI

Jak to wygląda w praktyce

Przed: kontroler zagrzebany w dekoratorach. Po: same trasy, z dokumentacją mieszkającą obok, w pliku towarzyszącym.

users.controller.ts

@WithDocs()
@Controller('users')
export class UsersController {
  constructor(private readonly users: UsersService) {}

  @Get(':id')
  findOne(@Param('id') id: string) {
    return this.users.findOne(id);
  }
}

users.controller.docs.ts

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' }),
    ],
  },
});

Tylko przy starcie, zero narzutu na żądanieTen sam wynik OpenAPI co przy dekoratorach inlineKonwencja pliku towarzyszącego, jak *.spec.ts

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.

Więcej niż zwykładokumentacja Swagger.