[Spring] Swagger Header 설정 방법

Spring에서 Swagger Header 설정 방법에 대해 알아보겠습니다.

API 마다 설정

각 API 마다 @ApiImplicitParam을 통해 인증 정보(토큰)를 입력하도록 설정합니다.

@ApiImplicitParams({@ApiImplicitParam(name = "Authorization", value = "JWT Token",
      required = true, dataType = "string", paramType = "header") })
@PostMapping("/auth/test")
public ResponseEntity<?> authTest() {
  System.err.println("authTest");
  return ResponseEntity.ok("test ok");
}

이 방법은 API 개수가 많아질 경우 코드 양이 늘어나고 가독성이 나빠집니다. 그리고 Swagger 를 통해 테스트 진행 시 각 API 마다 인증 정보를 입력해야 한다는 번거로움이 생기게 됩니다.

Authroize 버튼 활성화

SWagger Version 2.9.2부터는 번거로움을 없애주는 기능이 생겼습니다. Swagger 화면 상단 부분에 Autorize 버튼이 생겼습니다. Autorize 버튼을 클릭하면 모든 API에 일괄 인증 할 수 있도록 해주는 인증 정보를 입력받는 창이 뜹니다.

설정

먼저 maven 또는 gradle 설정을 합니다.

<dependency>
  <groupId>io.springfox</groupId>
  <artifactId>springfox-swagger2</artifactId>
  <version>2.9.2</version>
</dependency>

<dependency>
  <groupId>io.springfox</groupId>
  <artifactId>springfox-swagger-ui</artifactId>
  <version>2.9.2</version>
</dependency>

dependencies {
  compile group: 'io.springfox', name: 'springfox-swagger2', version: '2.9.2'
  implementation group: 'io.springfox', name: 'springfox-swagger-ui', version: '2.9.2'
}

SwaggerConfig 클래스를 생성하고 코드들을 추가합니다. 중요한 것은 ApiKey 를 유의해야 합니다. 프로젝트마다 사용하는 인증 key 가 다르므로 확인해서 입력합니다.

import java.util.Arrays;
import java.util.List;

import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;

import springfox.documentation.builders.ApiInfoBuilder;
import springfox.documentation.builders.PathSelectors;
import springfox.documentation.builders.RequestHandlerSelectors;
import springfox.documentation.service.ApiInfo;
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 springfox.documentation.swagger.web.DocExpansion;
import springfox.documentation.swagger.web.ModelRendering;
import springfox.documentation.swagger.web.OperationsSorter;
import springfox.documentation.swagger.web.TagsSorter;
import springfox.documentation.swagger.web.UiConfiguration;
import springfox.documentation.swagger.web.UiConfigurationBuilder;
import springfox.documentation.swagger2.annotations.EnableSwagger2;

/**
 * Swagger 자동 문서화 웹 생성을 위한 Spring MVC 설정
 * @author hgko
 *
 */
@Configuration
@EnableSwagger2
public class SwaggerConfig {

    @Bean
    public Docket api() {
        return new Docket(DocumentationType.SWAGGER_2)
              .useDefaultResponseMessages(false) // 웹 페이지에서 디폴트 설정되는 ResponseMessages 부분 표시하지 않음
              .select()
              .apis(RequestHandlerSelectors.basePackage("com.hgko.controller")) // Controller에서 api 추출
              .paths(PathSelectors.any())
              .build()
              .apiInfo(swaggerInfo())
              .securityContexts(Arrays.asList(securityContext()))
              .securitySchemes(Arrays.asList(apiKey()));
    }

    public ApiInfo swaggerInfo() {
        return new ApiInfoBuilder()
                .title("Server API Documentation")
                .description("서버 API에 대한 연동 문서입니다")
                .version("0.0.1")
                .build();
    }

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

    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));
    }
}

기존 API 코드에서 @ApiImplicitParams 부분을 제거합니다.

@PostMapping("/auth/test")
public ResponseEntity<?> authTest() {
  System.err.println("authTest");
  return ResponseEntity.ok("test ok");
}

설정은 다 끝났습니다. Swagger 화면에서 정상적으로 동작하는지 확인할 수 있습니다.