2022 스마일게이트 윈터데브캠프를 통해 성장하기 8 - 스웨거(Springdocs)로 API 문서 제공

 

API 문서화를 위해 Springdocs 도입

프론트엔드에 API 를 테스트해 볼 수 있는 화면을 제공

 

"Springfox"의 경우 2020년 이후 활동이 없는 상태라, Springdoc를 사용하였습니다.

 

의존성 추가

implementation 'org.springdoc:springdoc-openapi-ui:1.6.14'

 

application.yml 설정

springdoc:
  api-docs:
    path: /chat-api-docs
  default-consumes-media-type: application/json
  default-produces-media-type: application/json
  swagger-ui:
    operations-sorter: alpha
    tags-sorter: alpha
#    http://localhost:8080/swagger-ui/index.html
    path: /swagger-ui.html
    disable-swagger-default-url: true
    doc-expansion: none
  paths-to-match:
    - /chatting/**

 

 

Config 클래스 작성

@Configuration
public class SwaggerConfig {

    @Bean
    public GroupedOpenApi publicApi(){
        return GroupedOpenApi.builder()
                .group("v1-plop")
                .pathsToMatch("/chatting/**")
                .build();
    }

    @Bean
    public OpenAPI openAPI(){
        String title = "Plop Chat-service API Docs";
        String description = "Plop Messenger App REST API Document - Chat";

        SecurityScheme securityScheme = new SecurityScheme()
                .type(SecurityScheme.Type.HTTP).scheme("bearer").bearerFormat("JWT")
                .in(SecurityScheme.In.HEADER).name("Authorization");
        SecurityRequirement schemaRequirement = new SecurityRequirement().addList("bearerAuth");

        return new OpenAPI()
                .components(new Components().addSecuritySchemes("bearerAuth",securityScheme))
                .security(Arrays.asList(schemaRequirement))
                .info(new Info().title(title)
                        .description(description)
                        .version("v0.0.1"));
    }

}

 

 

API 정보 - 메소드

예시)

@Tag(name="room", description = "채팅방 API")
@Slf4j
@RestController
@RequestMapping("/chatting/room")
@RequiredArgsConstructor
public class ChatRoomController {

    @Operation(summary = "그룹 채팅방 생성", description = "그룹 채팅방 생성시 웹소켓으로 생성 정보 멤버들에게 전달", responses = {
            @ApiResponse(responseCode = "201", description = "생성 성공", content = @Content(schema = @Schema(implementation = RespRoomDto.class))),
            @ApiResponse(responseCode = "400", description = "초대한 상대방id가 없음", content = @Content(schema = @Schema(implementation = ErrorResponseDto.class))) })
    @PostMapping("/v1/group-creation")
    public ResponseEntity<RespRoomDto> groupCreation(@RequestHeader("Authorization") String jwt, @Valid @RequestBody ReqGroupDto reqGroupDto){
        String userId = getTokenToUserId(jwt);
        reqGroupDto.setCreator(userId);

        RespRoomDto respRoomDto = chatRoomMongoService.createGroup(reqGroupDto);

        producers.sendRoomMessage(RoomMessageDto.builder()
                .receivers(reqGroupDto.getMembers())
                .respRoomDto(respRoomDto)
                .build());
        return new ResponseEntity<>(respRoomDto,HttpStatus.CREATED);
    }

 

 

API 정보 - 모델

@Schema(description = "1:1 방생성 요청")
@Setter
@Getter
public class ReqDmDto {
    @Schema(description = "요청하는 유저 id")
    private String creator;
    @NotEmpty
    @Schema(description = "요청받는 유저 id")
    private String message_to;
}

@Schema 로 부가 설명