[스프링] 2. swagger ui 설정하기(1)

일단 Swagger 를 써야하는 이유에 대해 간단히 생각해보고 코드를 정리해야겠다. 

swagger는 api를 정리해서 관리하고, 확인하기 편하게 해준다. 

swagger ui를 통해 url 주소에서 적혀있는 path와, 요청의 method들을 정리해 보여준다. 

이를 통해 내가 만든 페이지가 어떻게 되어있고, 분류나 기능들을 한번에 볼 수 있다. 

코드를 정리해보자면, 계층적으로는

• api
  • apiInfo
  • apiKey
  • securityContext
    • defaultAuth

로 이루어져 있으며, 코드는 아래와 같다. 

@Import(BeanValidatorPluginsConfiguration.class)
@Configuration
@EnableWebMvc
// http://localhost:8080/swagger-ui/index.html
public class SwaggerConfig {

    @Bean
    public Docket api() {
        return new Docket(DocumentationType.OAS_30)
                .apiInfo(apiInfo())
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.swprogramming"))
                .paths(PathSelectors.any())
                .build()
                .securityContexts(Arrays.asList(securityContext()))
                .securitySchemes(Arrays.asList(apiKey()));
    }

    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("게시판만들기")
                .license("janghee5395@gmail.com")
                .licenseUrl("https://github.com/JangAJang/Board_Upgraded")
                .version("1.0")
                .build();
    }

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

    private SecurityContext securityContext() {
        return SecurityContext.builder().securityReferences(defaultAuth())
                .operationSelector(oc -> oc.requestMappingPattern().startsWith("/api/")).build();
    }

    private List<SecurityReference> defaultAuth() {
        AuthorizationScope authorizationScope = new AuthorizationScope("global", "accessEverything");
        return List.of(new SecurityReference("Authorization", new AuthorizationScope[] {authorizationScope}));
    }
}

defaultAuth

기본적인 인증 방식을 설정해준다. 이를 SecurityReference의 리스트형으로 만들어 반환해준다. 

 

 

SecurityContext

만들어진 인증 방식을 가져와 이를 SecurityContext의 securityReference에 담아준다. 

SecurityContext는 Authentication 객체가 저장되는 저장소로, 언제든지 꺼내 Authentication에 사용할 수 있게 해준다. 

이렇게 defaultAuth를 통해 인증 방식을 설정하고, operationSelector를 통해 매핑 패턴을 /api로 시작하는 것들만 모아 반환한다. 

 

ApiKey

인증키 방식을 설정해준다. Authorization을 할 때, header에서 Bearer토큰을 가져와 사용하게 설정되어있다. 이후, JWT로 바꾸어 설정해줄 것이다. 

 

이렇게 4개의 메서드로 swagger를 설정해주기 위한 준비를 끝냈다. 

이를 @Bean메서드에서 Docket에 담아 반환해준다. 

 

swagger-ui 주소를 호출하면 설정된 것을 토대로 swagger ui를 볼 수 있게 해준다. 

하지만 여기까지 했더니 404에러가 났다. 분명 공부했던대로 했을 때 됐었는데...는 무슨..하핳

 

지금 만들고 있는 프로젝트가 Spring Security를 적용한 프로젝트기 때문에 문제가 있다. 이 부분에 대해서 다음 게시글에서 정리해야겠다.