Conas a ghineann tú doiciméadú API le Swagger?

Question

Accepted Answer

Comhpháirtíonn NestJS le **Swagger/OpenAPI** trí `@nestjs/swagger` chun **doiciméadú API idirghníomhach a ghiniúint go huathoibríoch** ó do chód — controllers, routes, DTOs, agus decorators. Déanann sé UI inbhraite ar féidir le forbróirí pointí deiridh a fhiosrú agus a thástáil, agus é fanainte i gcomhordú leis an chód.

## Swagger a shocrú

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

Le cúpla líne, scanann Swagger do app agus feidhmíonn sé doiciméadú idirghníomhach ag `/api/docs` — ag léiriú do routes, paraiméadair, agus DTOs go huathoibríoch.

## DTOs agus freagartha a dhocúmentiú

```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;
}
```

Cuireann decorators `@ApiProperty` tuairimí, samplaí, agus srianta ar réimsí DTO, ag saibhriú an scéim ghinte. (Tá a lán infheartha go huathoibríoch ó chineálacha TypeScript agus decorators `class-validator` — is féidir leis an `CLI plugin` an bhullaí seo a laghdú fiú.)

## Pointí deiridh a dhocúmentiú

```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) {}
}
```

Cuireann decorators cosúil le `@ApiTags`, `@ApiOperation`, agus `@ApiResponse` tuairimí, grúpanna pointí deiridh, agus réimsí freagartha féideartha in iúl.

## Cad a gheobhaidh tú

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

## Cén fáth a bhíonn tábhacht ann

Tá doiciméadú API riachtanach d'aon API a úsáidtear ag daoine eile — foireann frontend, feidhmchláir fón póca, comhpháirtithe tríú páirtí, nó fiú thú féin amach anseo — agus déanann comhpháirtíochtaí Swagger NestJS doiciméadú ar ardchaighdeán a tháirgeadh an-éasca agus iontaofa.

Is é an buntáiste príomha nach bhfuil doiciméadú **ginte go huathoibríoch ó an chód** (controllers, routes, DTOs, agus decorators), agus go fanaíonn sé **i gcomhordú** leis an bhfíor-bhainistríochtaí in ionad a bheith i bhfad as dáta cosúil le doiciméadú scríofa de láimh a théann as dáta go dochúlach.

Tá sé luachmhar é a thuiscint toisc go ndéanann doiciméadú API ar scoth an taithí forbróra a fheabhsú go mór agus cuireann sé laghdú ar fhrithchuid comhtháthúcháin: ligeann an **UI Swagger** idirghníomhach do thomhaltóirí pointí deiridh a fhiosrú agus a *thástáil* go díreach sa bhróimseoir, agus is féidir leis an **speicifiú OpenAPI** ginte tiomáint ghiniúint SDK cliant agus tástáil chonradh.

Tá an fhios a bheith agat conas Swagger a shocrú, an doiciméadú a shaibhriú le decorators (`@ApiProperty`, `@ApiTags`, `@ApiOperation`, `@ApiResponse`), agus fíordheimhniú a dhocúmentiú ina eolas praiticiúil, fabhraitheoirí-riachtanach — is ionad prófesúnta agus tásc ar chéim ar doiciméadú APIs, agus ní gá a bheith ag fánúint fúithi. Toisc go bhfuil NestJS ag baint an-úsáid as a struchtúr deacóra/DTO chun an oiread sin a ghiniúint go huathoibríoch (le dícheall beag breise), níl scéal ar bith nach bhfuil fhéadfaidh doiciméadú ar nós sain a bhheith ann, rud a chuireann tábhacht ó bheith ann, ar chumas ar-luachmhar i dtionscnaimh NestJS fíor.