Swagger란? 어떻게 쓰지?

지니🧸·2023년 8월 28일

Spring Boot & JPA

목록 보기

27/35

Swagger: Rest API를 자동으로 문서화하여 API 호출 및 테스트 과정을 편리하게 해준다

1. Swagger 의존성 추가

implementation group: 'io.springfox', name: 'springfox-swagger-ui', version: '2.9.2'
implementation group: 'io.springfox', name: 'springfox-swagger2', version: '2.9.2'

2. Swagger UI 환경설정(config)

Docket: Swagger 프레임워크의 핵심 인터페이스로 쓰이는 Java 객체이자 builder

@Bean
public Docket api() {
    return new Docket(DocumentationType.SWAGGER_2)
        	.useDefaultResponseMessages(false) 
            .groupName(API_VERSION) 
            .select() 
            .apis(RequestHandlerSelectors.basePackage("패키지명")) 
            .paths(PathSelectors.ant("/**/")) 
            .build()
            .apiInfo(metaData())
            .securityContexts(Arrays.asList(securityContext()))
            .securitySchemes(Arrays.asList(apiKey()));
}

useDefaultResponseMessages(boolean) - Swagger에서 제공하는 응답코드(200, 401, 403, 404)에 대한 기분 메시지 사용 여부
groupName(API_VERSION) - 여러 Docket Bean 생성시 충돌을 막기 위해 버전 명시
select() - ApiSelectorBuilder 생성
apis(RequestHandlerSelectors.basePackage("패키지명")) - api 스펙이 작성된 패키지 명시
paths(PathSelectors.ant("/**/")) - path 조건에 해당하는 api를 찾아 문서화
apiInfo(api_info_custom_method()) - 제목, 설명 등 문서 정보 호출
securityContexts(Arrays.asList(securityContext())) - api 작업에 사용할 기본 인증 방식 목록
securitySchemes(Arrays.asList(apiKey())) - Swagger에서 사용할 api 인증 방식 목록

security context 메서드 정의

private SecurityContext securityContext() {
	return SecurityContext
    		.builder()
            .securityReferences(defaultAuth())
            .build();
}

default auth 메서드 정의

private List<SecurityReferences> defaultAuth() {
	AuthorizationScope authorizationScope = new AuthorizationScope("global", "accessEverything");
    AuthorizationScope[] authorizationScopes = new AuthorizationScope[1];
    authorizationScopes[0] = authorizationScope;
    return Arrays.asList(new SecurityReference("JWT", authorizationScopes));
}

전역 authorization scope을 사용한다

api key 메서드 정의

ApiKey - Swagger 내 인증방식으로 JWT, Bearer, Authorization이 존재한다

private ApiKey apiKey() {
    return new ApiKey("JWT", "Authorization", "header");
}

전체 코드

@Configuration
@EnableSwagger2 //Swagger2 버전 활성화
public class SwaggerConfig {
	private static final String API_NAME = "api name";
    private static final String API_VERSION = "0.0.1";
    private static final String API_DESCRIPTION = "api description";
    
    @Bean
    public Docket api() {
    	return new Docket(DocumentationType.SWAGGER_2)
        		.useDefaultResponseMessages(false) 
                .groupName(API_VERSION) 
                .select() 
                .apis(RequestHandlerSelectors.basePackage("패키지명"))
                .paths(PathSelectors.ant("/**/")) 
                .build()
                .apiInfo(metaData())
                .securityContexts(Arrays.asList(securityContext()))
                .securitySchemes(Arrays.asList(apiKey()));
    }
    
    private ApiInfo metaData() {
    	return new ApiInfoBuilder
        		.title("제목")
                .description("설명")
                .version("0.0.1")
                .termsOfServiceUrl("Terms of service")
                .license("Apache License Version 2.0")
                .licenseUrl("https://www.apache.org/licenses/LICENSE-2.0")
                .build();
    }
    
}