docfy patch-spec

Patcht een al gebouwd OpenAPI-document, volledig via statische analyse (ts-morph), zonder require() van enig docsbestand.

Waarom dit bestaat

Dit is een handmatige, CI-gedreven manier om het ene ding te omzeilen dat de runtime-pijplijn van DocfyModule structureel niet kan: werken onder de webpack: true build-modus van de NestJS CLI (zie De CLI-plugin voor het automatische, aanbevolen alternatief, dat dezelfde analyse bij elke build uitrekent in plaats van als losse stap). patch-spec omzeilt de webpack-muur door te matchen op path + HTTP-methode, berekend op dezelfde manier als check/coverage/lint al doen, in plaats van de live controllerklasse-referentie nodig te hebben.

Gebruik

bash
npx nestjs-docfy patch-spec --spec <path-or-url> [options]
bash
# Patch a running app's served document
npx nestjs-docfy patch-spec --spec http://localhost:3000/api-json --out openapi.json

# Patch a file already written to disk
npx nestjs-docfy patch-spec --spec dist/openapi.json --out dist/openapi.json

Opties

OptionDefaultDescription
--spec <path|url>(required)A local openapi.json, or a URL (e.g. a running app's /api-json)
--out <path>stdoutWhere to write the patched document
--root <path>.Project root directory
--tsconfig <path>auto-detectedPath to tsconfig.json
--pattern <glob>**/*.controller.tsGlob pattern to find controllers
--format <format>tsDocsbestandsformaat om naar te zoeken: ts of js
--quietfalseSuppress all output except errors

Wat er samengevoegd wordt

Gematcht op path + HTTP-methode tegen het basisdocument:

  • ApiTags → samengevoegd in tags (laat nooit tags vallen die het basisdocument al had)
  • ApiOperation({ summary, description, deprecated }) → overschrijft die velden
  • ApiResponse({ status, description, schema, example, examples }) → samengevoegd per statuscode (andere statuscodes blijven onaangeroerd); wordt geen schema/type meegegeven, dan valt het terug op het opgeloste return-type van de methode zelf, dezelfde DTO/class-validator/interface-inferentie die generate al doet, inclusief een oneOf van $ref's wanneer het return-type een union is van ≥2 benoemde DTO's/entiteiten (bijv. Promise<UserDto | AdminDto>)
  • ApiBody({ schema, examples }) → zet requestBody, met dezelfde return-type-achtige fallback naar het opgeloste type van de @Body()-parameter, inclusief dezelfde union → oneOf-afhandeling (example wordt hier bewust niet gelezen, want het echte ApiBodyOptions-type van @nestjs/swagger heeft alleen examples, in tegenstelling tot ApiResponse, dat beide ondersteunt)
  • ApiBearerAuth() → toegevoegd aan security
  • ApiParam / ApiQuery / ApiHeader → samengevoegd in parameters op naam + locatie: een echt nieuwe parameter wordt toegevoegd, maar een die al bestaat (bijv. @nestjs/swagger genereert automatisch een kale required: true-entry puur via reflectie voor elk @Query()/@Param()-gedecoreerd argument) krijgt zijn velden overlegd, niet weggegooid. enum wordt gelezen uit een array-literal (enum: ['a', 'b']) of een referentie naar een TS-enum, ook een die uit een ander bestand geïmporteerd is (enum: Role), en het type van het schema wordt afgeleid als number wanneer elke opgeloste waarde numeriek is, anders string

What this does not do

Bewust afgebakend

Dit commando is bewust afgebakend, geen volledige herimplementatie van de decorator-semantiek van @nestjs/swagger: anyOf (geen TS-constructie mapt op "any of" zoals een union-type natuurlijk op oneOf mapt), links/callbacks (@nestjs/swagger zelf heeft voor geen van beide een decoratoroptie), en elk decoratorargument dat geen literal is (een variabele, een functieaanroep, een spread) worden met rust gelaten in plaats van geraden. Beter een veld laten zoals het basisdocument het al had, dan er iets verkeerds in patchen. Een union-return-type of @Body()-payload wordt alleen een oneOf wanneer elke tak oplost naar een benoemde DTO/entiteit. Routes die een docsbestand documenteert maar die niet bestaan in --spec worden gerapporteerd als waarschuwing, niet stilletjes weggelaten of als fout gemeld.