SwaggerConfig
swagger : 스웨거는 Rest API를 설계, 빌드, 문서화 및 사용하는데 도움되는 openAPI 사양을 중심으로 구축 된 오픈 소스 도구 세트이며
테스트 할 수 있는 UI를 제공한다
의존성
// swagger dependency
implementation "io.springfox:springfox-boot-starter:3.0.0"
implementation "io.springfox:springfox-swagger-ui:3.0.0"- 강사님 : https://krksap.tistory.com/2172
- SwaggerConfig
설정 클래스를 정의한 뒤 @EnableSwagger2 어노테이션을 선언해주고 @Bean 어노테이션을 이용해서 Docket 객체를 빈으로 등록
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import springfox.documentation.builders.PathSelectors;
import springfox.documentation.builders.RequestHandlerSelectors;
import springfox.documentation.service.ApiKey;
import springfox.documentation.service.AuthorizationScope;
import springfox.documentation.service.SecurityReference;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spi.service.contexts.SecurityContext;
import springfox.documentation.spring.web.plugins.Docket;
import java.util.Arrays;
import java.util.List;
@Configuration
public class SwaggerConfig {
@Bean
public Docket api() {
return new Docket(DocumentationType.OAS_30)
.securityContexts(Arrays.asList(securityContext()))
.securitySchemes(Arrays.asList(apiKey()))
.select()
.apis(RequestHandlerSelectors.any())
.paths(PathSelectors.any())
.build();
}
private SecurityContext securityContext() {
return SecurityContext.builder()
.securityReferences(defaultAuth())
.build();
}
private List<SecurityReference> defaultAuth() {
AuthorizationScope authorizationScope = new AuthorizationScope("global", "accessEverything");
AuthorizationScope[] authorizationScopes = new AuthorizationScope[1];
authorizationScopes[0] = authorizationScope;
return Arrays.asList(new SecurityReference("Authorization", authorizationScopes));
}
private ApiKey apiKey() {
return new ApiKey("Authorization", "Authorization", "header");
}
}테스트
- 이미지 기준 우측 하단 Authorize 클릭
- 해당 창이 뜹니다
- Bearer <로그인 후 반환된 토큰을 넣어주세요 >
ex) Bearer yJhbGciOiJIUzI1NiJ9.eyJ1c2VyTmFtZSI6InNlb3l1biIsImlhdCI6MTY3MTY3MzY4OCwiZXhwIjoxNjcxNjc3Mjg4fQ.cnieU_gPAXZHMW_xgtb2rrWj-yjyOmb3fJ8gZdW8hv4
- 이후 API 테스트 진행
execute 클릭
Swagger
@EnableSwagger2
- Swagger2 버전을 활성화 하겠다는 어노테이션
Docket
- swagger 설정을 할 수 있게 도와주는 클래스
- API 자체에 대한 정보는 컨트롤러에서 작성한다
메서드
-
useDefaultResponseMessages(): false로 설정하면 swagger에서 제공해주는 응답코드(200, 401, 403, 404)에 대한 기본 메시지를 제거해준다
-
groupName(): docket bean이 한개일 경우 생략해도 상관없으나, 둘 이상일 경우 충돌을 방지해야하므로 설정해줘야한다
-
select(): ApiSelectorBuilder를 생성하여 apis()와 paths()를 사용할 수 있게 해준다
-
apis(): api 스펙이 작성되어 있는 패키지를 지정한다. 즉 컨트롤러가 존재하는 패키지를 basepackage로 지정하여 해당 패키지에 존재하는 API를 문서화 한다
ex) javable > controller 안에 api controller가 있기 때문에 basePackage를 javable.controller로 지정 -
paths(): apis()로 선택되어진 API중 특정 path 조건에 맞는 API들을 다시 필터링하여 문서화한다.
PathSelectors.any()로 설정하면 패키지 안에 모든 API를 만번에 볼 수 있다. -
apiInfo(): 제목, 설명 등 문서에 대한 정보들을 설정하기 위해 호출
ParameterBuilder + globalPerationParameters()
- parameterBuilder와 globalOperationParameters()를 이용해서 아래와 같이 swagger의 전체 API에서 보여줄 파라미터를 설정해줄 수도 있다
\
globalResponseMessage()
: 모든 operation에 공통된 응답 메시지를 작성해줄 수도 있다.
@Bean
public Docket apiV1() {
List<ResponseMessage> responseMessages = new ArrayList<>();
responseMessages.add(new ResponseMessageBuilder()
.code(200)
.message("OK")
.build());
responseMessages.add(new ResponseMessageBuilder()
.code(404)
.message("Not Found Error")
.build());
responseMessages.add(new ResponseMessageBuilder()
.code(500)
.message("Internal Server Error")
.build());
return new Docket(DocumentationType.SWAGGER_2)
.groupName("groupName1")
.select()
.apis(RequestHandlerSelectors.
basePackage("com.app.edit"))
.paths(PathSelectors.ant("/v1/api/**"))
.build()
.apiInfo(apiInfo())
.globalResponseMessage(RequestMethod.GET, responseMessages);
}
controller 적용
import io.swagger.annotations.Api;
import io.swagger.annotations.ApiOperation;
import io.swagger.annotations.ApiParam;
import org.springframework.web.bind.annotation.PostMapping;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RestController;
@Api(value = "hello", tags = {"swagger", "v1", "api"})
@RequestMapping("/v1/api")
@RestController
public class SwaggerController {
@ApiOperation(value = "this is test!", notes = "note!!!!!")
@PostMapping("/test")
public String test(@ApiParam(name = "first param", value = "first value", required = true) String input,
@ApiParam(name = "second param", value = "second value", required = false) String input2) {
return "test";
}
}@Api
: 해당 클래스가 swagger 리소스라는 것을 명시해준다
- value: 사용자 지정 이름을 붙일 수 있음. tags 사용시 무시된다
- tags: 사용하여 여러개의 태그를 정의할 수도 있다.
@ApiOperation
: 한 개의 Operation을 선언한다
- value: API에 대한 요약을 작성한다. 제대로 표시되려면 120자 이하여야함
- notes: API에 대한 자세한 설명을 작성
@ApiParam
: 파라미터에 대한 정보를 명시한다
- name: 파라미터 이름을 작성한다
- value: 파라미터 설명을 작성한다
- required: 필수 파라미터이면 true 또는 false를 작성한다
참고 블로그
