docfy patch-spec

Faz patch de um documento OpenAPI já buildado, inteiramente via análise estática (ts-morph), sem require() de nenhum docs file.

Por que existe

Este é o workaround para a única coisa que o pipeline runtime do DocfyModule estruturalmente não consegue fazer: trabalhar sob o modo de build webpack: true do NestJS CLI. patch-spec contorna isso completamente casando por path + método HTTP, computado do mesmo jeito que check/coverage/lint já fazem, em vez de precisar da referência viva da classe do controller.

Uso

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

Options

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>tsDocs file format to look for: ts ou js
--quietfalseSuppress all output except errors

What gets merged

Casado por path + método HTTP contra o documento base:

  • ApiTags → unificado em tags (nunca dropa tags que o documento base já tinha)
  • ApiOperation({ summary, description, deprecated }) → sobrescreve esses campos
  • ApiResponse({ status, description, schema }) → mesclado por status code (outros status codes intactos); quando não há schema/type, cai no return type resolvido do método, mesma inferência de DTO/class-validator/interface que generate já faz
  • ApiBody({ schema }) → define requestBody, com o mesmo fallback estilo return-type para o tipo resolvido do parâmetro @Body()
  • ApiBearerAuth() → anexado a security
  • ApiParam / ApiQuery / ApiHeader → anexados a parameters, deduplicados por nome + localização

What this does not do

Escopo intencional

Este comando é intencionalmente escopado, não é uma reimplementação completa da semântica de decorators do @nestjs/swagger: enums, oneOf/anyOf, examples, links, callbacks, e qualquer argumento de decorator que não seja um literal (uma variável, uma chamada de função, um spread) são deixados como estão em vez de serem chutados, pois é melhor deixar um campo como o documento base já tinha do que dar patch de algo errado. Rotas que um docs file documenta mas que não existem em --spec são reportadas como warnings, não silenciosamente dropadas nem tratadas como erro.