Swagger
적용한 프로젝트 스펙
적용 방법

Swagger

서버를 만들고 그 서버와 통신하기 위한 방법을 문서화 시켜야 한다.
주소, 요청에 담길 헤더, 바디 등
어디에 어떻게 요청을 해야 하고 기대되는 응답은 이렇다 라는 내용을 문서화할때
엑셀, 노션 등과 같이 직접 수동적으로 작업할 수 있지만

Swagger 라는 라이브러리를 통해 이런 문서화를 자동화 시킬 수 있다.
직접 사용을 할 땐 Spring 환경에서 진행을 했다.
이 Swagger 는 자바의 스프링 뿐만 아니라, Python이나 다른 언어의 환경에서도 지원되는 라이브러리이다.

---

적용한 프로젝트 스펙

Spring-boot : 3.2.3
Spring-boot-swagger : 2.2.0

---

적용 방법

현재 스프링 Swagger 를 적용시킬 수 있는 라이브러리의 종류는 2가지이다.
하나는 Spring-fox 다른 하나는 Spring-doc 이다.
스프링의 2번대 스프링 버전의 경우 Spring-fox 를 적용시킬 수 있지만,
Spring-fox 는 3번대 스프링 버전에서는 호환이 되지 않는다고 한다.
따라서 이 프로젝트에서는 Spring-doc을 적용 시켰다.

build.gradle에 라이브러리 추가

implementation 'org.springdoc:springdoc-openapi-starter-webmvc-ui:2.2.0'

1번대 버전을 적용 시켰을때 400오류가 뜨면서 오류가 발생했다.
해당 오류에 대해서 검색 결과 위 버전을 적용시키면 해결이 되었다.

application.yml 생성 및 설정

springdoc:
  swagger-ui:
    # swagger-ui 접근 경로. default 값은 /swagger-ui.html이다.
    path: /swagger-custom-ui.html
    
  api-docs:
    path: /api-docs

  # request 기본 타입
  default-consumes-media-type: application/json

  # response 기본 타입
  default-produces-media-type: application/json

  # 해당 패턴에 매칭되는 controller만 swagger-ui에 노출한다.
  paths-to-match:
    - /api/**
      
  # 현재 시큐리티를 통해 로그인 처리를 하고 있기 때문에 로그인에 대한 엔드포인트 추가
  show-login-endpoint: true

현재 Swagger 의 설정들이다.
더 많은 설정들이 존재하지만 현재에서 필요한 설정들만을 사용했다.
시큐리티를 사용하고 있기 때문에 jwt토큰을 통한 요청에 대한 설정도 필요하다.
Swagger 는 시큐리티 환경을 기본세팅으로 두고 있지 않기 때문에 추가적인 설정이 필요하다.

---

SecurityConfig permitAll 설정

//기본적으로 요청에 대해서 허용을 할 주소들 따로 클래스로 설정
@NoArgsConstructor
public class AuthenticatedMatchers {
    public static final String[] swaggerArray = {
            "/api-docs",
            "/swagger-ui-custom.html",
            "/v3/api-docs/**",
            "/swagger-ui/**",
            "/api-docs/**",
            "/swagger-ui.html",
            "/swagger-custom-ui.html"
    };
}

//SecurityConfig에서 위의 클래스내에 swaggerArray의 모든 경로들 permitAll설정
@Bean
    public SecurityFilterChain securityFilterChain(HttpSecurity httpSecurity) throws Exception {
        httpSecurity.authorizeHttpRequests((req) -> {req
                .requestMatchers(AuthenticatedMatchers.swaggerArray).permitAll()
                //다른 경로들
                .anyRequest().authenticated();
        });
    }

Spring-security 설정을 해둔 상태기 때문에 현재 서버에서 Swagger ui에 접속을 할때는 토큰에 대한 인증, 인가를 하면 안된다.
따라서 따로 클래스안에서 허용할 엔드포인트들을 모아놓고 SecurityConfig파일내에서 허용을 시켜줘야 한다.

---

SwaggerConfig 설정

@OpenAPIDefinition(
        info = @Info(
                title = "goods 서버 API 명세서",
                description = "goods 서버에서 REST하게 작성된 API 명세서",
                version = "v1"
        )
)
@Configuration
public class SwaggerConfig {
    @Bean
    @Profile("!Prod")
    public OpenAPI openAPI() {
        String jwtSchemeName = "Bearer 토큰 입력";
        SecurityRequirement securityRequirement = new SecurityRequirement().addList(jwtSchemeName);
        
        Components components = new Components()
                .addSecuritySchemes(jwtSchemeName, new SecurityScheme()
                        .name(jwtSchemeName)
                        .type(SecurityScheme.Type.HTTP)
                        .scheme("Bearer")
                        .bearerFormat("Bearer"));

        return new OpenAPI()
                .addSecurityItem(securityRequirement)
                .components(components);
    }
}

위와 같이 Configuration파일을 하나 만들어서 토큰인증에 관련된 설정을 해주고
http://localhost:8080/swagger-custom-ui.html로 들어가면
Swagger에서 설정한 내용대로 html을 만들어서 제공해주고,
Configuration에서 설정한 내용을 토대로 jwt토큰으로 한번 인증을 하면 이후 요청에 대해서는 그냥 요청이 가능하다.

SwaggerConfig 설정이 없어도 해당 url로 문제없이 들어가질 수 있지만 테스트요청을 할 수 없다.