Swagger உடன் API documentation-ஐ எப்படி உருவாக்குவீர்கள்?

Question

Accepted Answer

NestJS உங்கள் code-இலிருந்து — controllers, routes, DTOs, மற்றும் decorators — **interactive API documentation-ஐ auto-generate செய்ய** `@nestjs/swagger` மூலம் **Swagger/OpenAPI** உடன் ஒருங்கிணைகிறது. இது developers endpoints-ஐ ஆராயவும் test செய்யவும் முடியும் ஒரு browsable UI-ஐ உருவாக்குகிறது, code உடன் ஒத்திசைவில் வைக்கப்படுகிறது.

## Swagger-ஐ அமைத்தல்

```ts
// main.ts
import { SwaggerModule, DocumentBuilder } from "@nestjs/swagger";

const config = new DocumentBuilder()
  .setTitle("Users API")
  .setDescription("The users API documentation")
  .setVersion("1.0")
  .addBearerAuth()                       // document JWT auth
  .build();

const document = SwaggerModule.createDocument(app, config);
SwaggerModule.setup("api/docs", app, document);   // serve the UI at /api/docs
```

ஒருசில lines-உடன், Swagger உங்கள் app-ஐ scan செய்து `/api/docs`-இல் interactive docs-ஐ வழங்குகிறது — உங்கள் routes, parameters, மற்றும் DTOs-ஐ தானாகவே பிரதிபலிக்கிறது.

## DTOs மற்றும் responses-ஐ document செய்தல்

```ts
export class CreateUserDto {
  @ApiProperty({ example: "ann@example.com", description: "User email" })
  email: string;

@ApiProperty({ minLength: 8 })
  password: string;

@ApiPropertyOptional()                 // optional field in the docs
  age?: number;
}
```

`@ApiProperty` decorators DTO fields-க்கு descriptions, examples, மற்றும் constraints-ஐச் சேர்த்து, உருவாக்கப்பட்ட schema-ஐ வளப்படுத்துகின்றன. (அதிகமானவை TypeScript types மற்றும் `class-validator` decorators-இலிருந்து தானாகவே inferred ஆகின்றன — `CLI plugin` இந்த boilerplate-ஐயும் கூட குறைக்க முடியும்.)

## Endpoints-ஐ document செய்தல்

```ts
@ApiTags("users")                        // group endpoints in the UI
@Controller("users")
export class UsersController {
  @Post()
  @ApiOperation({ summary: "Create a user" })
  @ApiResponse({ status: 201, description: "User created", type: User })
  @ApiResponse({ status: 400, description: "Invalid input" })
  create(@Body() dto: CreateUserDto) {}
}
```

`@ApiTags`, `@ApiOperation`, மற்றும் `@ApiResponse` போன்ற decorators descriptions-ஐச் சேர்த்து, endpoints-ஐ group செய்து, சாத்தியமான responses-ஐ document செய்கின்றன.

## நீங்கள் பெறுவது

```text
✓ Interactive UI (Swagger UI) — browse, read, and TEST endpoints in the browser
✓ Auto-generated, always in sync with the code (no separate doc to maintain)
✓ The OpenAPI spec (JSON) — usable to generate client SDKs, for contract testing, etc.
✓ Request/response schemas, validation rules, auth requirements all documented
```

## இது ஏன் முக்கியம்

மற்றவர்களால் — frontend teams, mobile apps, third-party integrators, அல்லது உங்கள் எதிர்கால சுயம் கூட — பயன்படுத்தப்படும் எந்த API-க்கும் API documentation அவசியம், மேலும் NestJS-இன் Swagger integration உயர்தர docs-ஐ உருவாக்குவதை குறிப்பிடத்தக்க அளவில் எளிதாகவும் நம்பகமாகவும் ஆக்குகிறது.

முக்கிய நன்மை என்னவென்றால் documentation ஆனது **code-இலிருந்து auto-generate செய்யப்படுகிறது** (controllers, routes, DTOs, மற்றும் decorators), எனவே கையால் எழுதப்பட்ட docs தவிர்க்கமுடியாமல் காலாவதியாகி விலகுவது போலல்லாமல், அது உண்மையான implementation உடன் **ஒத்திசைவில்** இருக்கிறது.

நல்ல API docs developer experience-ஐ வியத்தகு முறையில் மேம்படுத்தி integration friction-ஐக் குறைப்பதால் அதைப் புரிந்துகொள்வது மதிப்புமிக்கது: interactive **Swagger UI** ஆனது consumers-ஐ browser-இல் நேரடியாக endpoints-ஐ ஆராயவும் *test* செய்யவும் அனுமதிக்கிறது, மேலும் உருவாக்கப்பட்ட **OpenAPI spec** ஆனது client SDK generation மற்றும் contract testing-ஐ இயக்க முடியும்.

Swagger-ஐ எப்படி அமைப்பது, decorators (`@ApiProperty`, `@ApiTags`, `@ApiOperation`, `@ApiResponse`) மூலம் docs-ஐ வளப்படுத்துவது, மற்றும் authentication-ஐ document செய்வது என அறிந்திருப்பது நடைமுறை, அடிக்கடி தேவைப்படும் அறிவாகும் — நன்கு-documented APIs ஒரு தொழில்முறை தரம் மற்றும் தரமான back-end வேலையின் அடையாளமாகும்.

NestJS தனது decorator/DTO அமைப்பைப் பயன்படுத்தி மிகவும் தானாகவே உருவாக்குவதால் (குறைந்தபட்ச கூடுதல் முயற்சியுடன்), சிறந்த docs வைத்திருக்காமல் இருப்பதற்கு சிறிய சாக்குப்போக்கே உள்ளது, இது உண்மையான NestJS projects-இல் ஒரு முக்கியமான, உயர்-மதிப்பு திறனாக ஆக்குகிறது.