[Spring] Swagger 3.x 적용하기

Swagger란

Swagger(스웨거)는 개발자가 REST API 서비스를 설계, 빌드, 문서화할 수 있도록 하는 프로젝트이다.
Swagger는 다음과 같은 경우에 유용하게 사용된다.

• 다른 개발팀과 협업을 진행할 경우
• 이미 구축되어있는 프로젝트에 대한 유지보수를 진행할 경우
• 백엔드의 API를 호출하는 프론트엔드 프로그램을 제작할 경우

기능

• API 디자인
• API 빌드
• API 문서화
• API 테스팅
• API 표준화

장점

• API 정보 현행화 가능
• API를 통해 Parameter, 응답 정보, 예제 등 Spec 정보 전달이 용이함
  실제 사용되는 Parameter로 테스트 가능

Swagger Tool 종류

• Swagger Codegen : Swagger로 정의된대로 클라이언트/서버 코드를 생성하는 CLI 툴이다.
• Swagger UI : Swagger UI는 Swagger API 명세서를 HTML 형식으로 확인할 수 있는 툴이다.
• Swagger Editor : Swagger 표준에 따른 API 설계서/명세서를 작성하기 위한 에디터이다.

Springfox Swagger와 SpringDoc, 어떤 차이가 있지?

최근 Spring에서 밀고 있는건 이름에서도 느낌이 오겠지만 SpringDoc이다.
SpringDoc가 세팅하는 것에 있어서 더 쉬운 것 같다.

Springfox Swagger 적용하기

의존성 추가

/* build.gradle */
dependencies {
    // ..
    implementation 'io.springfox:springfox-boot-starter:3.0.0'
    // ..
}

🚨이런 에러가 뜬다면, 추가해주자.

org.springframework.context.ApplicationContextException: Failed to start bean 'documentationPluginsBootstrapper'; nested exception is java.lang.NullPointerException

/* application.properties */
spring.mvc.pathmatch.matching-strategy = ANT_PATH_MATCHER

/* application.yml */
spring:
    mvc:
      pathmatch:
            matching-strategy: ant_path_matcher

Config 추가

@Configuration
public class SwaggerConfig {

    @Bean
    public Docket api() {
        return new Docket(DocumentationType.OAS_30)
                .useDefaultResponseMessages(false)
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.example.springswagger.controller"))
                .paths(PathSelectors.any())
                .build()
                .apiInfo(apiInfo());
    }

    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("Practice Swagger")
                .description("practice swagger config")
                .version("1.0")
                .build();
    }
}

Controller 적용

@RestController
public class HelloController {

    @Operation(summary = "test hello", description = "hello api example")
    @ApiResponses({
            @ApiResponse(responseCode = "200", description = "OK !!"),
            @ApiResponse(responseCode = "400", description = "BAD REQUEST !!"),
            @ApiResponse(responseCode = "404", description = "NOT FOUND !!"),
            @ApiResponse(responseCode = "500", description = "INTERNAL SERVER ERROR !!")
    })
    @GetMapping("/hello")
    public ResponseEntity<String> hello(@Parameter(description = "이름", required = true, example = "Park") @RequestParam String name) {
        return ResponseEntity.ok("hello " + name);
    }
}

접속하기

• Swagger2: http://localhost:8080/swagger-ui.html
• Swagger3: http://localhost:8080/swagger-ui/index.html

SpringDoc 적용하기

의존성 추가

/* build.gradle */
dependencies {
    // ..
	implementation group: 'org.springdoc', name: 'springdoc-openapi-ui', version: '1.5.9'
    // ..
}

application.yml 추가

springdoc:
  default-consumes-media-type: application/json
  default-produces-media-type: application/json
  swagger-ui:
    path: /swagger-ui.html
    disable-swagger-default-url: true
    display-query-params-without-oauth2: true

접속하기

• http://localhost:8080/swagger-ui.html

관련코드는 여기서

🍪https://github.com/hocaron/Spring-Study/tree/main/spring-swagger

참고

• https://sarc.io/index.php/development/1974-swagger
• https://bcp0109.tistory.com/326?category=981824