Express용 Swagger
설치
npm install --save @nestjs/swagger swagger-ui-express
JavaScript
복사
세팅 - main.ts
const config = new DocumentBuilder()
.setTitle('C.I.C')
.setDescription('cat')
.setVersion('1.0.0')
.build();
const document: OpenAPIObject = SwaggerModule.createDocument(app, config);
SwaggerModule.setup('docs', app, document);
JavaScript
복사
main.ts에 위의 코드를 넣어준다.
→ setup 옆에 ‘docs’는 swagger api의 엔드포인트이다, 즉 localhost:8000/docs/ 로 요청을 하게 되면 swagger문서가 나온다.
확인
위와 같은 모습으로 Swagger문서를 확인할 수 있다.
근데 이렇게 사용하면 POST /cats 가 무슨 역할을 하는 건지 알수가 없다.
CatController > ApiOperation 데코레이터
설명이 필요한 메소드 위에 ApiOperation 데코레이터를 달아서 해당 메소드에 대한 설명이 가능하다.
ApiOperation 적용 확인
요청 DTO - swagger 표시
요청 데이터 예시 표시란에 아무것도 들어가 있지 않아서, 사용하기 어렵다.
ApiProperty 데코레이터
이렇게 필드마다 @ApiProperty 를 명시를 해줘서, 예시와 설명을 넣으면 된다.
cat.request.dto.ts 전체코드
확인
이렇게 예시로 요청데이터의 형태를 확인할 수 있다. 결과값 또한 어떤 형식으로 반환되는지도 적용해야된다.
cat.response.dto.ts
위의 내용은 요청시의 데이터 형식에 관한 이야기이고, 응답 데이터 또한 표시를 해줘야 되는데, 그것을 위해서 cat.response.dto.ts 를 생성하였다.
파일 생성
dto 폴더 내부에 cat.response.dto.ts 를 생성한다.
cat.response.dto
import { ApiProperty } from '@nestjs/swagger';
export class CatResponseDTO {
@ApiProperty({
example: '20980293',
description: 'id',
})
id: string;
@ApiProperty({
example: 'ssar@nate.com',
description: 'email',
})
email: string;
@ApiProperty({
example: 'blue',
description: 'name',
})
name: string;
}
JavaScript
복사
readOnlyData 에 명시된 필드를 모두 추가하면 되고,
여기서는 class-validator는 삭제하면 된다.
controller 설정
@ApiResponse 로 상태코드와 설명을 추가하면 문서에도 성공시 실패시에 대해서 명확하게 파악할 수 있다.
그리고 성공시에 어떤 데이터를 보낼지에 대해서 정의된 responseDTO 를 명시해주면 된다.
Swagger 확인
이렇게 서버가 통신에 성공하면 어떤 모습인지, 에러시에는 또 어떤 모습인지 확인할 수 있다.
Swagger로 테스트
1.
try it out
2.
요청 데이터 넣기
요청데이터 데로 Excute를 클릭
3.
반환 데이터 확인
이렇게 요청을 통해서 서버에 어떻게 반환이 되었는지 확인이 가능하다
상속을 사용해서 코드 중복 줄이기
현재 구조에서는 requestDTO, responseDTO 에 중복되는 @ApiProperty 때문에 효율적이지 못하다. 그래서 스키마에 모든 설정을 합치고, 스키마를 상속받는 방향으로 구현해보자.
설정이 추가된 cat.schema 코드
dto에서 Cat 상속받기
이렇게 요청/응답 DTO 모두 Cat을 상속 받아서 속성을 이어 받을 수 있게 되었다.
하지만, 이 구조에서는 여전히 민감한 정보를 포함하거나, 불필요한 정보를 빼야되는 설정이 필요하다.
PickType / OmitType
PickType은 스키마에서 특정 요소만 사용할 때 사용하고, OmitType은 특정요소를 다 사용하되 몇 개만 빼고 싶은 경우에 사용한다.
이렇게 PickType으로 Cat 스키마의 email, name만 따로 상속하겠다 라는 의미로 사용이 가능하다.
여기서 id 속성은 몽고디비가 만들어 주는 것이므로 스키마에 없다.
위처럼 따로 설정해줘야 된다.
CatResponseDto 코드
CatRequestDto 코드
CORS 설정
Cross Origin Resource Sharing 이라는 단어의 약자로 웹 애플리케이션에서 서로 다른 출처 간의 리소스 요청을 제어하여 보안을 강화하는 메커니즘이다.
CORS 등록 - main.ts
main.ts 내부에 app.enableCors를 추가해주고 옵션을 추가해서 사용하면 된다.
→ origin: true 옵션
이 옵션이 true로 되어 있으면, 우리 백엔드는 모든 출처에서의 요청이 허용되는 상태이다. 개발할 때는 이게 true로 설정이 되어있어도 되지만, 배포시에는 우리가 만든 프론트만 요청이 허용될 수 있도록 주소를 명시 해줘야 된다.
요런 식으로