작업 환경

• Spring Boot (Gradle)
• Swagger3.0

---

Spring Boot 스웨거 적용

dependency 추가

build.gradle

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

Configuration 추가

SwaggerConfig.java

package com.artlogy.someTest.config;

import java.util.HashSet;
import java.util.Set;

import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.web.servlet.config.annotation.EnableWebMvc;

import springfox.documentation.builders.ApiInfoBuilder;
import springfox.documentation.builders.PathSelectors;
import springfox.documentation.builders.RequestHandlerSelectors;
import springfox.documentation.service.ApiInfo;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2;

@Configuration
public class SwaggerConfig {
    private ApiInfo apiInfo(){
        return new ApiInfoBuilder()
            .title("Test Open API")
            .description("Test Swagger Demo")
            .version("1.0")
            .build();
    }
    @Bean
    public Docket api(){
        return new Docket(DocumentationType.OAS_30)
                .consumes(getConsumeContentTypes())
                .produces(getProduceContentTypes())
                .useDefaultResponseMessages(false)
                .apis(RequestHandlerSelectors.basePackage("com.antsome.husome"))
                .paths(PathSelectors.any())
                .build()
                .apiInfo(apiInfo());

    private Set<String> getConsumeContentTypes() {
        Set<String> consumes = new HashSet<>();
        consumes.add("application/json;charset=UTF-8");
        consumes.add("application/x-www-form-urlencoded");
        return consumes;
    }

    private Set<String> getProduceContentTypes() {
        Set<String> produces = new HashSet<>();
        produces.add("application/json;charset=UTF-8");
        return produces;
    }
}

Docket

Swagger 설정의 핵심이 되는 Bean 입니다.
Docket에서 가장 자주 쓰이는 설정 정보는 다음과 같습니다.

useDefaultResponseMessage

false로 설정시, swagger에서 기본적으로 제공해주는 응답코드에 대한 메세지를 제거합니다.

groupName

만약 하나의 API에 여러개의 스웨거가 필요 할 경우 구분하기 위한 이름입니다.

select

ApiSelectorBuilder를 생성합니다.
Select() 이후로 스웨거가 적용 될 경로에 관한 설정을 합니다.

apis

api 스펙이 작성되어 있는 패키지를 지정합니다.

paths

apis()로 선택된 API중 path 조건에 맞는 API들만 필터링 하여 문서화 합니다.

apiInfo

스웨거 문서의 제목, 설명등을 설정합니다.

consumes

HTTP 요청시 어떤 문서 타입을 지정할 수 있는지를 나타냅니다.

produces

응답 객체 반환시 어떤 문서 타입으로 반환하는지 나타냅니다.

---

Security + Swagger

스웨거는 프로젝트 관련자만 본다는 약속하에 작성되는 것이기 때문에,
굳이 번거롭게 Security를 적용 할 필요는 없다.
( 릴리즈 버전은 스웨거를 빼면 그만이기 때문에 )

물론 인증/인가가 필요한 앤드포인트도 있기 때문에 전체 설정은 보안을 무시 하되
꼭 필요한 것들만 적용하는 방식을 배워보자.

Security 무시하기

WebSecurity.java

...
// for swagger
.antMatchers("/swagger-ui/**","/swagger-resources/**","/v3/api-docs")
.permitAll()
...

위 처럼 security 설정에 swagger 관련한 접근은 모두 허용해준다.

스웨거 부분 Security 적용 ( jwt )

SwaggerConfig.java

    public Docket api(){
        return new Docket(DocumentationType.OAS_30)
                .consumes(getConsumeContentTypes())
                .produces(getProduceContentTypes())
                .useDefaultResponseMessages(false)
                #Context는 적용범위
                .securityContexts(Arrays.asList(securityContext()))
                #Schema는 jwt schema
                .securitySchemes(Arrays.asList(aceessKey(),refreshKey()))
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.antsome.husome"))
                .paths(PathSelectors.any())
                .build()
                .apiInfo(apiInfo());
    }
    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 aceessKey() {
        return new ApiKey("accessToken", "Authorization", "header");
    }
    private ApiKey refreshKey() {
        return new ApiKey("refreshToken", "RefreshToken", "header");
    }

---

Swagger Anotation

자주 쓰는 것 위주로 알아보자.

@Api

@Api(tags = "Artlogy", description = "@Api 기능 테스트")
@RestController
@RequestMapping(path="/api")
public class MailTestController{
	...
}

Controller 단위의 Api를 식별해주는 어노테이션이다.

@Operator

	@Operation(summary ="테스트 이메일 보내기", description = "테스트 이메일을 보내보자.")
    @PostMapping(value="/approval/test")
    public MailDto.Response getSendApprovalTest(@RequestBody MailDto.Request body){
        MailDto.Response mailRes = new MailDto.Response();
        mailRes.setAddress("artlogy@github.com");
        return mailRes;
    }

endpoint 단위의 Api를 식별해주는 어노테이션이다.

@Shema

        @Schema(description = "주소", example = "artlogy@github.com", type="String")
        private String address;
        @Schema(description = "제목", example = "제목입니다.", type="String")
        private String title;
        @Schema(description = "내용", example = "안녕하세요. artlogy 장현욱입니다.", type="String")
        private String message;
        @Schema(description = "파일 이름", example = "현욱짱.file", type="String")
        private String fileName;

Response/Request로 반환/주입 할 데이터들을 식별하는 어노테이션이다.

---