@nestjs/swagger 패키지,, @apiquery, @apiparams 데코레이터, 언제 @apiquery를 쓰고 언제 @apiparams를 쓰니

swagger를 이용하기 위한 거라 생각 안 해도 됨 -> @Apiparames 등 등

 

swagger=. 프론트에게 스펙 전달하는 개발 문서 api document 

---

[ openAi와 공부 ]

Q: nest.js를 쓰는데 import{ApiBody, ApiParam, ApiQuery, ApiResponse, ApiTags} from '@nestjs/swagger'를 설명해줘

 

 

@nestjs/swagger 패키지는

Nest.js 프레임워크에서 Swagger 문서 생성 및 API 문서화를 지원하기 위한 패키지입니다.

 

이 패키지는

API 엔드포인트의 설명, 요청 및 응답 모델, 파라미터 등을 문서화하고

 

Swagger UI 또는 기타 Swagger 관련 도구를 사용하여 API 문서를 생성하고 제공합니다.

 

 

@nestjs/swagger 패키지에서 사용되는 주요 데코레이터 및 클래스에 대한 설명은 다음과 같습니다:

1. @ApiTags(tags: string[]):
   • 이 데코레이터는 컨트롤러 클래스나 메서드에 태그(태그 그룹)를 추가할 때 사용됩니다. 이 태그는 Swagger UI에서 API 문서를 그룹화하고 분류하는 데 사용됩니다.
2. @ApiBody(options: ApiBodyOptions):
   • 이 데코레이터는 요청 본문의 형식과 설명을 정의할 때 사용됩니다. ApiBodyOptions 객체를 통해 요청 본문의 예제, 데이터 형식, 설명 등을 지정할 수 있습니다.
3. @ApiParam(options: ApiParamOptions):
   • 이 데코레이터는 경로 파라미터나 쿼리 스트링 파라미터의 형식과 설명을 정의할 때 사용됩니다. ApiParamOptions 객체를 통해 파라미터의 이름, 데이터 형식, 설명 등을 지정할 수 있습니다.
4. @ApiQuery(options: ApiQueryOptions):
   • 이 데코레이터는 API 엔드포인트의 쿼리 스트링 파라미터의 형식과 설명을 정의할 때 사용됩니다. ApiQueryOptions 객체를 통해 쿼리 파라미터의 이름, 데이터 형식, 설명 등을 지정할 수 있습니다.
5. @ApiResponse(options: ApiResponseOptions):
   • 이 데코레이터는 API 엔드포인트의 응답 형식과 설명을 정의할 때 사용됩니다. ApiResponseOptions 객체를 통해 응답 모델, 상태 코드, 설명 등을 지정할 수 있습니다.

이러한 데코레이터와 옵션을 사용하면

Nest.js 애플리케이션에서 API 엔드포인트를 정의하고

해당 엔드포인트의 설명 및 구조를 문서화할 수 있습니다.

 

Swagger UI와 같은 도구를 사용하여

이러한 정보를 기반으로 자동으로 API 문서를 생성할 수 있습니다.

 

이는 API 개발 및 문서화를 간단하게 만들어주며 API 사용자에게 이해하기 쉬운 문서를 제공하는 데 도움이 됩니다

 

 

---

언제 @apiquery를 쓰고 언제 @apiparams를 쓰니

 

@ApiQuery와 @ApiParam은

Nest.js의 Swagger 모듈을 사용하여 API 문서를 생성할 때 사용되는 데코레이터입니다.

 

이들은 API 엔드포인트의 파라미터 및 쿼리 스트링 값을 설명하고 문서화하는 데 사용됩니다.

다음은 언제 어떤 데코레이터를 사용해야 하는지에 대한 가이드입니다:

 

1. @ApiQuery:

• @ApiQuery 데코레이터는 주로 쿼리 스트링 파라미터(query parameters)를 문서화할 때 사용됩니다.
• 예를 들어, GET 요청의 쿼리 스트링 파라미터를 문서화하고 설명할 때 사용합니다.

path = 특정한 값 뽑을 때 --> 상세페이지 
query = 옵션을 줄 때 (filter/order정렬/pagination/searching 검색) --> 전체 목록 페이지 

Project 2 - 2일차 : [Restful API] 세션/ Path vs. Query parameter

 

사용 예제:

@Get()
@ApiOperation({ summary: 'Get users' })
@ApiQuery({ name: 'page', type: Number, required: false, description: 'Page number' })
@ApiQuery({ name: 'limit', type: Number, required: false, description: 'Items per page' })
findAll(@Query('page') page: number, @Query('limit') limit: number) {
  // ...
}

---

2. @ApiParam:

• @ApiParam 데코레이터는 주로 경로 파라미터(path parameters)를 문서화할 때 사용됩니다.
• 예를 들어, 경로 파라미터를 문서화하고 설명할 때 사용합니다.

사용 예제:

@Get(':id')
@ApiOperation({ summary: 'Get user by ID' })
@ApiParam({ name: 'id', type: Number, description: 'User ID' })
findById(@Param('id') id: number) {
  // ...
}

---

<요약>

@ApiQuery 쿼리 스트링 파라미터를 문서화할 때 사용

@ApiParam 경로 파라미터를 문서화할 때 사용

 

path = 특정한 값 뽑을 때 --> 상세페이지 
query = 옵션을 줄 때 (filter/order정렬/pagination/searching 검색) --> 전체 목록 페이지 

Project 2 - 2일차 : [Restful API] 세션/ Path vs. Query parameter

 

 

두 데코레이터를 사용하여 API 문서를 작성하면

API 엔드포인트의 파라미터와 쿼리 스트링 값에 대한 정보를 클라이언트 또는 다른 개발자들에게 명확하게 전달할 수 있습니다.

 

---

[manager 정보 GET api ] (어드민에 로그인 한 manager)

@Get (‘:manager_id’)         // api 주소명을 우리가 지어줌 :id로 하면 params로 받음   
async manager(@Param('manager_id') managerId: number) {   
  console.log(managerId)
}

 

 // api 주소명을 우리가 ':manager_id'로 지어줌 :id로 하면 params로 받음 

// 함수명을 manger 로 한다 

// key:value -> key = managerId, 키값은 number