@WithDocs()でコントローラーをマークする

どのコントローラーがコンパニオンファイルを持つかをフラグ付けし、その後generateを実行します。

コントローラーをマークする

users.controller.ts
// users.controller.ts
import { Controller, Get, Post, Body } from "@nestjs/common";
import { WithDocs } from "nestjs-docfy";

@WithDocs()
@Controller("users")
export class UsersController {
  // route handlers only: no Swagger decorators here
}

コンパニオンファイルを生成する

CLIを実行してプロジェクトをスキャンし、コントローラーごとにあらかじめ内容を埋めた*.controller.docs.tsを生成します。

bash
npx nestjs-docfy generate

CLIは静的解析のみを使用し(コードは実行しません)、プロジェクトの構成を自動検出します。モノレポ、Nxワークスペース、Nest CLIモノレポのいずれにも対応しています。

ファイルシステムに触れずにプレビューするには:

bash
npx nestjs-docfy generate --dry-run

docsファイルを埋める

生成されるファイルには、推論されたサマリー、レスポンス型、一般的なエラーレスポンスがあらかじめ埋め込まれています。

users.controller.docs.ts
// Generated by nestjs-docfy: edit freely, use --force to merge new methods
import { docs } from "nestjs-docfy";
import { ApiTags, ApiOperation, ApiResponse, ApiBody } from "@nestjs/swagger";
import { UsersController } from "./users.controller";
import { CreateUserDto } from "./dto/create-user.dto";
import { UserEntity } from "./entities/user.entity";

docs(UsersController, {
  classDecorators: [ApiTags("users")],
  methods: {
    // GET / → async findAll(): Promise<UserEntity[]>
    findAll: [
      ApiOperation({ summary: "Find all" }),
      ApiResponse({ status: 200, description: "OK", type: [UserEntity] }),
    ],

    // POST / → async create(dto: CreateUserDto): Promise<UserEntity>
    create: [
      ApiOperation({ summary: "Create" }),
      ApiBody({ type: CreateUserDto }),
      ApiResponse({ status: 201, description: "Created", type: UserEntity }),
      ApiResponse({ status: 400, description: "Bad Request" }),
    ],
  },
});

ファイルは自由に編集してください。変更しても安全です。generateを再度実行しても既存のファイルはスキップされます。既存のファイルに触れず新しいメソッドだけをマージするには--forceを使ってください。