Springboot3 + Swagger + Jwt (2)

프로젝트 진행 이유 및 개발 환경

2024.06.20 - [BE/Java] - Springboot3 + Swagger + Jwt (1)

Springboot3 + Swagger + Jwt (1)

 

 

 

진행할 내용

1. Swagger 셋팅

 

 

 

---

Swagger란?

REST API 개발을 진행하는경우 Restful한 서비스를 만들때  @RestController를 읽어서 API 문서를 자동으로 생성해주고, API를 테스트 할 수 있는 UI를 제공하는 라이브러리

간편하게 사용할 수 있다는 장점이 있지만, 운영서버와 같은 환경에서는 외부로 노출되면 안되기 때문에 주의를 해야한다.

 

 

---

Swagger 종류

- Springfox

Spring 프레임워크를 사용하는 로젝트에서 Swagger를 사용할 수 있게 해주는 라이브러리.

3.00 버전을 기준으로 마지막 업데이트가 중단 (Maven Repository 기준 대략 2020년 7월)

 

 

- Springdoc

Spring 프레임워크를 사용하는 로젝트에서 Swagger를 사용할 수 있게 해주는 라이브러리.
webflux 라는 방식의 웹 개발을 지원하도록 개발되어있다.
yml 파일 설정을 통해 그룹 간 API 정렬이 가능하다.(가나다순, abc순)

 

 

위의 두가지 선택지중 버전업을 계속 하고있는 Springdoc을 사용하기로 결정!

 

 

 

---

Swagger 적용하기

Springdoc Swgger 3.0.0 적용

공식문서 : https://springdoc.org/

OpenAPI 3 Library for spring-boot

 

1. build.gradle 의존성 추가

   - 당연한 얘기지만 의존성 추가 후 gradle reload를 해줘야함 (간혹 reload를 안하고 안된다는 분들이 있기때문에..)

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

 

1. application.yml 의존성 추가

- application.properties보다 보기 편해서 yml로 작성

springdoc:
  api-docs: #api 설정
    path: /api   # api엔드포인트 설정
    groups: #그룹핑
      enabled: true
  swagger-ui:  #swagger ui 설정
    path: /swagger.html #swagger 접속 경로
    enabled: true
    groups-order: ASC #정렬
    tags-sorter: alpha #태그정렬기준
    operations-sorter: alpha #api정렬기준
    display-request-duration: true
    doc-expansion: none #tag 리스트 펼치기
  cache:
    disabled: true
  model-and-view-allowed: true
  default-produces-media-type: application/json
  default-consumes-media-type: application/json

 

3. SwaggerConfig.java 등록

package org.jjuni.swaggerjwt.config;

import io.swagger.v3.oas.models.OpenAPI;
import io.swagger.v3.oas.models.info.Info;
import lombok.RequiredArgsConstructor;
import org.springdoc.core.models.GroupedOpenApi;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;

@Configuration
@RequiredArgsConstructor
public class SwaggerConfig {

    @Bean
    public OpenAPI customOpenAPI() {
        return new OpenAPI()
                .info(new Info()
                        .title("Springboot+Swagger+JWT")
                        .version("1.0")
                        .description("초기 구축 셋팅 과정을 기록하는 swagger 입니다."));
    }
}

- 간혹 INFO 부분에서 에러가 나는 경우가있는데, intellij에 해당 라이브러리를 한번에 import 하지 못하는듯함.

아래 import가 잘 되어있는지 확인하자!!

import io.swagger.v3.oas.models.info.Info;

 

 

 

이제 localhost:8080/swagger.html 로 접속하면 기본 페이지가 뜬다.

 

 

 

 

추가적으로 필요한 내용들은 작업하면서 추가할 예정!

 

 

 

 

 

refs

dependency 참조 사이트 : https://colabear754.tistory.com/130

 

[Swagger] Spring Boot 3.0.X 버전에서 Swagger UI 접속 시 404 에러가 발생할 때

설정파일 참조 사이트 : https://beforb.tistory.com/166

[Swagger3] 1. springdoc-openapi를 이용한 Swagger3 설정하기(+Swagger 옵션)