Swagger સાથે API ডকুમેન્টેશન કેવી રીતે તৈયાર કરશો?

Question

Accepted Answer

NestJS **Swagger/OpenAPI** સાથે `@nestjs/swagger` દ્વારા ઇન્ટીગ્રેટ થાય છે જે તમારા કોડ — કંટ્રોલર્સ, રૂટ્સ, DTOs, અને ડેકોરેટર્સમાંથી **સ્વચાલિત રીતે ઇન્ટરેક્ટિવ API ડોક્યુમેન્ટેશન** પ્રસ્તુત કરે છે। તે એક બ્રાઉజેબલ UI તૈયાર કરે છે જ્યાં ડેવલપર્સ એન્ડપોઈન્ટ્સ શોધી શકે અને તેને ટેસ્ટ કરી શકે, જે કોડ સાથે સમન્વયમાં રાખવામાં આવે છે।

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

માત્ર કેટલી લાઇનો સાથે, Swagger તમારી એપ્લિકેશનને સ્કેન કરે છે અને `/api/docs` પર ઇન્ટરેક્ટિવ ડોક્યુમેન્ટેશન સર્વ કરે છે — સ્વચાલિત રીતે તમારા રૂટ્સ, પેરામીટર્સ, અને DTOs પ્રતિબિંબિત કરે છે।

## DTOs અને રિસ્પોન્સ્ડોક્યુમેન્ટ કરવું

```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` ડેકોરેટર્સ DTO ફીલ્ડ્સમાં વર્ણનો, ઉદાહરણો, અને પ્રતિબંધો ઉમેરે છે, જે જનરેટ કરેલ સ્કીમાને સમૃદ્ધ કરે છે। (TypeScript પ્રકારો અને `class-validator` ડેકોરેટર્સમાંથી મોટું ભાગ સ્વચાલિત રીતે આમાંથી ઉતરી આવે છે — `CLI plugin` આ બોઇલર્પ્લેટ પણ ઘટાડી શકે છે।)

## એન્ડપોઈન્ટ્સ ડોક્યુમેન્ટ કરવું

```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` જેવા ડેકોરેટર્સ વર્ણનો ઉમેરે છે, એન્ડપોઈન્ટ્સને જૂથીય કરે છે, અને સંભવિત રિસ્પોન્સ્ડોક્યુમેન્ટ કરે છે।

## તમને શું મળે છે

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

## શા માટે તે મહત્વપૂર્ણ છે

API ડોક્યુમેન્ટેશન અન્યો દ્વારા વપરાતી કોઈ પણ API માટે આવશ્યક છે — ફ્રન્ટએન્ડ ટીમ્સ, મોબાઈલ એપ્લિકેશન્સ, તૃતીય-પક્ષ ઇન્ટીગ્રેટર્સ, અથવા તમારું ભવિષ્યનું આત્મ — અને NestJS નું Swagger ઇન્ટીગ્રેશન ઉચ્ચ-ગુણવત્તાના ડોક્યુમેન્ટેશન પ્રસ્તુત કરવાને નોંધપાત્ર રીતે સરળ અને વિશ્વાસપાત્ર બનાવે છે।

મુખ્ય ફાયદો એ છે કે ડોક્યુમેન્ટેશન **કોડમાંથી સ્વચાલિત રીતે તૈયાર** થાય છે (કંટ્રોલર્સ, રૂટ્સ, DTOs, અને ડેકોરેટર્સ), તેથી તે વાસ્તવિક અમલીકરણ સાથે **સમન્વયમાં** રહે છે, આત્માર્પણ લખાયેલ ડોક્યુમેન્ટેશનની જેમ જૂનું થતું નથી।
	તેને સમજવું મૂલ્યવાન છે કારણ કે સારો API ડોક્યુમેન્ટેશન ડેવલપર અનુભવમાં નાટકીય સુધારો લાવે છે અને ઇન્ટીગ્રેશન ઘર્ષણ ઘટાવે છે: ઇન્ટરેક્ટિવ **Swagger UI** ગ્રાહકોને બ્રાઉઝર્માં સીધાં એન્ડપોઈન્ટ્સ શોધી કે ટેસ્ટ કરવા દે છે, અને જનરેટ કરેલ **OpenAPI spec** ક્લાઈન્ટ SDK જનરેશન અને કરાર પરીક્ષણ ચલાવી શકે છે।

Javascriptજાણવું કે Swagger કેવી રીતે સેટ અપ કરવું, ડેકોરેટર્સ (`@ApiProperty`, `@ApiTags`, `@ApiOperation`, `@ApiResponse`) સાથે ડોક્યુમેન્ટેશન સમૃદ્ધ કરવું, અને પ્રમાણીકરણ ડોક્યુમેન્ટ કરવું એ વ્યાવહારિક, વારંવાર જરૂરી જ્ઞાન છે — સારી તૈયારી કરેલ APIs એક વ્યાવસાયિક ધોરણ અને ગુણવત્તાના પશ્ચાદવર્તી કામનું હોદ્દો છે।

NestJS તેના ડેકોરેટર/DTO માળખો લાભ લે છે તેથી ઘણું કંઈ સ્વચાલિત રીતે જનરેટ કરે છે (ન્યૂનતમ વધારાના પ્રયાસ સાથે), તેથી સારો ડોક્યુમેન્ટેશન રાખવા માટે બહાનું નથી, આ વાસ્તવિક NestJS પ્રોજેક્ટમાં એક મહત્વપૂર્ણ, ઉચ્ચ-મૂલ્ય ક્ષમતા બનાવે છે।