그간 스웨거를 많은 삽질을 통해 사용하고 있었는데, 오늘 문득~!! 깨닳음을 얻어서 까먹기 전에 남긴다...
이런걸 두고 득도라고 하는건가?? 허허허~~ 오늘도 야근 당첨인 갑다~ 이거 쓰고 있을 시간 없는디...;;;;
무튼...
그동안 막연하게 알고 있던 내용인데, 스웨거는 두가지의 방법으로 설정을 할 수 있는거 같아 보인다.
(나도 야생에서 배운거라 정확한 내용은 아니다...ㅡㅡ;;)
첫번째
org.springdoc:springdoc을 사용해서 설정 하는 방법과,
두번째
io.springfox:springfox-boot-starter을 사용해서 설정 하는 방법...
설정은 두번째를 사용하면 훨씬~ 편하기는 하다 의존성 하나만 추가 하면 되기 때문이다 그렇다고 첫번째가 그렇게 불편한건 또 아니기 때문에 의존성 몇개만 더 추가 해주면 되고, 사용법은 두가지 방법이 상이 하기 때문에 어떤걸 사용하냐에 따라서 사용 할수 있는 어노테이션 또한 달라서 각자 맞는 방법의 어노테이션을 찾아 사용 하면 된다.
지금 여기서는 첫번째로 진행을 할거다...아래 의존성을 추가해 준다.
implementation 'org.springdoc:springdoc-openapi-ui:1.6.10'
implementation 'org.springdoc:springdoc-openapi-common:1.6.10'그리고 필요 하면 아래도 같이 추가해 준다.
(사실 아래는 언제 뭐 땜시 추가를 했는지 기억이 안난다...ㅡㅡ;;; 나이를 먹으니 점점...흑..잠시 눈물좀...ㅠㅠ)
implementation 'io.swagger.core.v3:swagger-annotations:2.2.1'
그리고 SwaggerConfig.java 에는 아래처럼...
@Bean
public OpenAPI openAPI() {
Info info = new Info().title("테스트 모바일 API")
.description("테스트 모바일 API")
.termsOfService("http://swagger.io/terms/")
.license(new License()
.name("Apache License Version 2.0")
.url("http://www.apache.org/licenses/LICENSE-2.0"));
return new OpenAPI()
.info(info);
}
@Bean
public GroupedOpenApi mobile(){
return GroupedOpenApi.builder()
.group("mobile")
.pathsToMatch("/mobile/**")
.packagesToScan("kr.co.gizmo80.test.order")
.build();
}
@Bean
public GroupedOpenApi web(){
return GroupedOpenApi.builder()
.group("web")
.pathsToMatch("/**")
.pathsToExclude("/mobile/**")
.packagesToScan("kr.co.gizmo80.test.order")
.build();
}이렇게 해줬다.
openAPI는 전체 API에 대한 공통적인 설명과 라이센스를 나타내고, 실제로 그룹 설정은 아래 있는
mobile(), web() 이다.
뭐 소스 보면 대충 감이 오겠지만 .group("mobile") 은 그룹명이고, .pathsToMatch("/mobile/**") 은 그룹으로 묶을 URL
.pathsToExclude("/mobile/**") 은 제외할 URL, .packagesToScan("kr.co.innosoft.tapex.order") 은 그룹으로 묶을 패키지가 된다.
이렇게 설정을 하고 스웨거를 실행 하면
헤더 부분에 group("mobile") 에 설정한 mobile과 web이 selectbox에 나온다.
select를 바꿀때 마다 mobile과 web의 그룹이 변경이 되는걸 확인 할 수 있다.
위 그룹을 응용을 하게 되면 .packagesToScan("kr.co.gizmo80.test.order")를 이용해서 컨트롤러 별로 그룹도 가능 하고, 버전별로 나눌수도 있을거 같다.
그리고 추가로 처음에 이야기 했던 두번째 방법 io.springfox로 스웨거를 설정 하게 되면 @Tag 어노테이션으로 그룹이 가능 하니
필요 한 방법으로 설정을 하면 될거 같다.
아래는 전체 SwaggerConfig.java 소스이고, 소스 아래 주석 부분이 io.springfox로 했을때 설정 하는 내용이다.
import io.swagger.v3.oas.models.OpenAPI;
import io.swagger.v3.oas.models.info.Info;
import io.swagger.v3.oas.models.info.License;
import org.springdoc.core.GroupedOpenApi;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
@Configuration
public class SwaggerConfig {
@Bean
public OpenAPI openAPI() {
Info info = new Info().title("테스트 모바일 API")
.description("테스트 모바일 API")
.termsOfService("http://swagger.io/terms/")
.license(new License()
.name("Apache License Version 2.0")
.url("http://www.apache.org/licenses/LICENSE-2.0"));
return new OpenAPI()
.info(info);
}
@Bean
public GroupedOpenApi mobile(){
return GroupedOpenApi.builder()
.group("mobile")
.pathsToMatch("/mobile/**")
.packagesToScan("kr.co.gizmo80.order")
.build();
}
@Bean
public GroupedOpenApi web(){
return GroupedOpenApi.builder()
.group("web")
.pathsToMatch("/**")
.pathsToExclude("/mobile/**")
.packagesToScan("kr.co.gizmo80.order")
.build();
}
// @Bean
// public Docket api() {
// return new Docket(DocumentationType.OAS_30)
// .useDefaultResponseMessages(false)
// .select()
// .apis(RequestHandlerSelectors.basePackage("kr.co.gizmo80.order"))
// .paths(PathSelectors.any())
// .build()
// .apiInfo(apiInfo())
// .directModelSubstitute(Timestamp.class, String.class);
// }
//
// private ApiInfo apiInfo() {
// return new ApiInfoBuilder()
// .title("테스트 모바일 API")
// .description("2022.08.09 모바일API/Web 통합.<br>" +
// "통합 하게 되면서 웹에서 세션을 사용하기 위해, RequestMapping에 모바일 접속용으로 /mobile/* prefix가 추가 되었다.<br>")
// .version("1.0")
// .build();
// }
}