SpringBoot Swagger 적용하기

Jae Hun Lee·2023년 2월 20일

SpringBoot Swagger 적용하기

Swagger란?

Swagger는 REST API를 설계, 구축, 문서화 및 사용하는 데 도움이 되는 OpenAPI 사양을 기반으로 구축된 오픈 소스 도구 세트입니다.

의존성 추가

https://mvnrepository.com/artifact/org.springdoc/springdoc-openapi-ui

Swagger는 두가지 버전의 라이브러리가 있는데
springfox-swagger, springdoc-openapi 두가지 중 요근래 많이 사용한다는 doc를 사용하겠다.
버전은 가장 최신버전 중 적당히 사용중인 버전으로 선택했다.

build.gradle

// https://mvnrepository.com/artifact/org.springdoc/springdoc-openapi-ui
    implementation group: 'org.springdoc', name: 'springdoc-openapi-ui', version: '1.6.11'

SwaggerConfig.java

public class SwaggerConfig {

    @Bean
    public GroupedOpenApi jwtApi() {
        return GroupedOpenApi.builder()
                .group("api") // 그룹설정
                .pathsToMatch("/**")
                .build();
    }

    @Bean
    public OpenAPI customOpenAPI() {
        SecurityRequirement securityRequirement = new SecurityRequirement().addList("Authorization");//JWT 전역 설정을 위해 추가
        return new OpenAPI()
                .addSecurityItem(securityRequirement)//JWT 전역 설정을 위해 추가
                .components(new Components()
                        .addSecuritySchemes("Authorization",
                                new SecurityScheme().type(SecurityScheme.Type.HTTP).scheme("bearer").bearerFormat("JWT")))//JWT 전역 설정을 위해 추가
                .info(new Info().title("Spring Boot API")
                        .description("API 예시입니다")
                        .version("0.0.1"));

    }
}

중간에 보면 JWT 전역 설정을 위해 추가라는 부분이있는데 저 부분들을 추가 해주게되면 아래 사진과 같이
authorize 버튼이 생기며 전역 설정이 가능해진다

application.yml

springdoc:
  swagger-ui:
    path: /swagger-ui.html
    use-root-path: true

위의 세개 파일을 적용 시킨 후
http://localhost:8080/swagger-ui/index.html에 접속해보면 다음과 같은 화면을 볼 수 있다.

Controller

@Tag(name = "게시판", description = "게시판 API 입니다.")
@RestController
@RequiredArgsConstructor
public class BoardController {

    private final BoardService boardService;

    @Operation(summary = "게시글 추가 메서드", description = "게시글 추가 메서드 입니다.")
    @PostMapping("/api/post") // 추가
    public ResponseEntity<Object> addBoard(@RequestBody BoardRequestDto boardRequestDto, @AuthenticationPrincipal UserDetailsImpl userDetails){

        return boardService.addBoard(boardRequestDto,userDetails.getUser());

    }
    @Operation(summary = "전체조회 메서드", description = "전체 조회 메서드 입니다.")
    @GetMapping("api/posts") // 전체 조회
    public List<BoardResponseDto> getBoard(){
        return boardService.getBoard();
    }
}

위의 @Tag와 @Operation을 적용시키면 아래와 같이 적용된다

그리고 아래와 같이 코드를 적용시키면 값에 설명을 달아줄 수 있다

 @Parameter(name = "id", description = "글의 ID값")
    @GetMapping("api/post/{id}") // 특정 글 조회
    public BoardResponseDto getIdBoard(@PathVariable Long id){
        return boardService.getIdBoard(id);
    }