spring boot 2.6.x에 swagger 3.0 설정해보자(+수정 openapi 3.0 2022.05.30)

Swagger란?

• API 문서 자동화 open api
  • api path, request, response 값 및 제약 조건 등을 문서화
• 파라미터를 넣어서 실제로 어떤 응답이 오는지 테스트 가능

 

Version

• spring boot 2.6.7
• swagger 3.0
• gradle 7.4.1

 

의존성 추가

implementation 'io.springfox:springfox-boot-starter:3.0.0'

• 기존 swagger 2.x 에서는 springfox-swagger-ui를 포함해줘야했다
• 하지만 3.x 부터는 stater에 해당 liberary가 모두 포함되어있다

 

Config 설정

@Configuration
public class SwaggerConfig extends WebMvcConfigurationSupport {

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

    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("YAPP20-BE-ToGaether API")
                .description("모임 기반 플랫폼 ToGaether API 문서")
                .version("1.0")
                .build();
    }
}

 

주의할 점

• basePackage()는 지정한 패키지의 api를 swagger에 나타낸다
• 나는 패키지 이름을 잘못 입력하여 꽤 오랜시간 삽질했다,,

 

Controller

@RestController
@Tag(name = "club", description = "모임 관련 API")
public class ClubController {

    @Operation(summary = "api simple explain", description = "api specific explain")
    @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 = "aa") @RequestParam String name) {
        return ResponseEntity.ok("hello " + name);
    }
}

 

이렇게 설정하면 documentationPluginsBootstrapper 에러가 발생한다

documentationPluginsBootstrapper 에러 해결 방법 을 참고하면 해결할 수 있다!

 

결과

• ~~/swagger-ui/index.html로 접속하면 된다!

 

Config

 

API

---

수정

 

 

프로젝트 하는 도중 swagger의 annotation이 제대로 작동하지 않아 기존 springfox를 사용하지 않고 openapi 3.0을 사용하여 swagger의 설정을 변경했다(2022.05.30)

 

위의 버전은 같고 바뀐 점은 springfox 대신 springdoc을 사용, config 설정, application.yaml이 달라졌다.

 

build.gradle

implementation group: 'org.springdoc', name: 'springdoc-openapi-ui', version: '1.5.9'

 

application.yaml

springdoc: 
  version: '1.0' //OpenApiConfig의 @Value에 들어가는 값
  api-docs:
    path: /api-docs //openApi 3을 이용하여 json 형식화 한 것의 경로
  default-consumes-media-type: application/json
  default-produces-media-type: application/json
  swagger-ui:
    operations-sorter: alpha //method는 http method 순
    tags-sorter: alpha
    path: /swagger-ui //swagger api 문서 경로
    disable-swagger-default-url: true
    display-query-params-without-oauth2: true
    doc-expansion: none
  paths-to-match:
    - /api/** //문서화할 api path

 

Config 설정

@Component
public class OpenApiConfig {

    @Bean
    public OpenAPI openAPI(@Value("${springdoc.version}") String appVersion) {
        Info info = new Info().title("YAPP20-BE-ToGaether API").version(appVersion)
                              .description("모임 기반 플랫폼 ToGaether API 문서")
                              .license(new License().name("Apache License Version 2.0").url("<http://www.apache.org/licenses/LICENSE-2.0>"));

        return new OpenAPI()
                .components(new Components())
                .info(info);
    }
}

• Open Api 프로퍼티 설정

 

spring security 사용 시 주의점

• 만약 spring security를 사용하면 security config에서 swagger 웹 페이지에 대한 permit 설정을 해줘야합니다!

 

 

api 세부 설정

• 앞서 작성한 “swagger 연동” 문서의 “적용” 참고

 

---

REFERENCES

swagger 설정

springfox 공식 문서

api Schema 설정

 

springdoc yaml 설정 공식문서

springdoc 참고 블로그