Api Docs로 어떤것을 사용할까?
Seminar-hub라는 세미나 관련 토이프로젝트를 진행하고 있습니다.
REST API를 만들면서 다른 이들에게 어떤 API인지 설명해주는 DOCS는 필수이기에, API Docs 자동화를 위한 라이브러리를 도입하기 위한 과정을 글로 작성해보게 되었습니다.
이번에 글을 작성하게 되면서 알게된 점으로는 API 문서 자동화에는 크게 2가지가 있습니다.
1. 반드시 테스트를 진행하고 그것을 기반으로 만들어주는 Spring Rest Docs
- 반드시 테스트를 진행해야하고, 그것을 기반으로 API문서가 생성됩니다. 그렇기에 코드가 변경되거나 오류가 발생하더라도 바로바로 알 수 있어서 신뢰성이 높습니다.
- 직접 테스트를 해볼 수가 없습니다.
2. 개발자가 직접 해당 API를 설명하고, 그것을 기반으로 만들어주는 OpenApi 3.0 Specification (일명 Swagger)
- 개발자가 코드로 해당 API를 설명하고 해당 어노테이션을 기반으로 API Docs 생성합니다. 코드가 중간에 변경되더라도 API Operation이 설명되지 않는다면 신뢰성이 낮아집니다.
- 직접 테스트를 해볼 수 있습니다.
이렇게 Spring RestDocs와 OpenApi 3.0 Specifiaction이 있습니다.
이 2가지에서 저는 OpenApi 3.0 Specifiaction을 사용하기로 마음먹었고, 이유로는 Postman을 사용하지 않고 웹페이지에서 바로 테스트를 진행할 수 있다는 점이 큰 편리함을 제공한다고 느꼈습니다.
( 추가로, 이전에는 SpringFox를 기반으로 하여 OpenApi 3.0 을 적용하지만 해당 라이브러리는 업데이트를 제공하지 않는 상황입니다. 그러므로 Spring Docs를 OpenApi 3.0 Specifiaction을 활용하시는 것을 추천드립니다. )
구현해보기
1. Build.gradle springdoc-openai-starter-webmvc-ui 2.0.2 를 가져옵니다.
implementation 'org.springdoc:springdoc-openapi-starter-webmvc-ui:2.0.2'
2. SpringdocConfig 파일을 만들고 아래의 내용을 넣습니다.
@OpenAPIDefinition
@Configuration
public class SpringdocConfig {
@Bean
public OpenAPI baseOpenAPI(){
return new OpenAPI().info(new Info().title("Spring DOC").version("1.0.0").description("Spring doc"));
}
}
- Title, Version , Description 을 설정합니다.
3. MemberController
@RestController
@RequestMapping("/member/")
@RequiredArgsConstructor
@Tag(name = "Member API")
public class MemberController {
private final MemberService memberService;
@PostMapping(value ="")
@Operation(summary = "Register a new member")
@ApiResponses(value = {
@ApiResponse(responseCode = "200", description = "Successful operation"),
@ApiResponse(responseCode = "400", description = "Invalid request payload")
})
public ResponseEntity<Long> register(
@ApiParam(value = "Member information", required = true)
@RequestBody MemberDTO memberDTO) {
log.info("-----------------register--------------");
log.info(memberDTO);
Long member_no = memberService.register(memberDTO);
return new ResponseEntity<>(member_no, HttpStatus.OK);
}
}- @Tag : Controller 이름
- @Operation : API 설명
- @ApiResponse : API 결과값(성공, 실패 모두 넣을 수 있음)
- @ApiParam : Parameter 설명
4. MemberDTO
@Data
@Builder
@AllArgsConstructor
@NoArgsConstructor
public class MemberDTO {
@Schema(description = "member_no")
private Long member_no;
@Schema(description = "member_id", format="email")
private String member_id;
@Schema(description = "member_password")
private String member_password;
}- @Schema : MemberDTO에 대한 설명
추가적으로, 만약 JWT를 Auth에 담아 Bearer 와 함께 인증방식으로 사용한다면, SpringDocConfig는 아래와 같이 설정하여 사용할 수 있습니다.
@OpenAPIDefinition
@Configuration
public class SpringdocConfig {
@Bean
public OpenAPI baseOpenAPI(){
Info info = new Info().title("Spring DOC").version("1.0.0").description("Spring doc");
String jwtSchemeName = "jwtAuth";
SecurityRequirement securityRequirement = new SecurityRequirement().addList(jwtSchemeName);
Components components = new Components()
.addSecuritySchemes
(jwtSchemeName
, new SecurityScheme().name(jwtSchemeName)
.type(SecurityScheme.Type.HTTP)
.scheme("bearer")
.bearerFormat("JWT"));
return new OpenAPI().info(info).addSecurityItem(securityRequirement).components(components);
}
}
이로써 설정이 끝났습니다.
이후에, Spring Security 관련하여서 아직 추가 설정이 필요합니다.
해당 내용은 나중에 Spring Security 설정 이후에 새로운 포스팅으로 남기도록 하겠습니다.
참고자료
'Spring Boot' 카테고리의 다른 글
| [Spring][Websocket] polling, Long polling, Streaming, WebSocket 간단한 구현 코드로 알아보기 (1) (1) | 2023.08.02 |
|---|---|
| [SpringBoot, JPA] 회원과 회원권한관리에서 OneToMany 대신 ElementCollection을 사용하는 경우 (0) | 2023.06.06 |