Swagger 설정

사용 이유

팀 프로젝트를 진행하면서 API 정보를 프론트 팀과 공유하기 위해 사용.

노션에 직접 URL과 파라미터, Response 등을 적어 주면서 API 정보를 공유했었는데

프로그램이 커지니 실수도 생기고 찾아보기도 힘들었다.

따라서, Swagger를 적용하여 자동으로 API 문서를 정리하도록 했다.

❓Swagger

---

Swagger는 OAS(Open Api Specification)를 위한 오픈소스 프레임워크이다.

• 즉, API의 문서를 자동으로 정리해주는 것.

Swagger를 통해서 Path, Request, Response, 조건 등을 한번에 알 수 있다.

API 문서 자동화뿐 아니라 Swagger를 통해 파라미터를 넣어 테스트를 진행할 수 도 있다.

 

Swagger를 사용하면 API 문서를 작성하는 시간을 절약할 수 있고 API 정보를 실시간으로 유지할 수 있다.

💡 Spring 에서 Swagger 사용하기

---

Spring에서 Swagger를 쉽게 사용할 수 있도록 도와주는 라이브러리는 2개 존재한다.

1. Springdoc
2. Springfox

Springfox 3.00 적용

Springfox를 통해 기본적인 문서화 및 테스트 기능을 제공하는 Swagger 작성

• 테스트시 JWT 기반의 인증을 제공할 수 있도록 설정

의존성 추가

implementation group: 'io.springfox', name: 'springfox-swagger-ui', version: '3.0.0'
implementation group: 'io.springfox', name: 'springfox-swagger2', version: '3.0.0'
implementation group: 'io.springfox', name: 'springfox-boot-starter', version: '3.0.0'

SwaggerConfig.java

@Configuration
@EnableSwagger2
@EnableWebMvc
public class SwaggerConfig extends WebMvcConfigurationSupport {

  @Override
  protected void addResourceHandlers(ResourceHandlerRegistry registry) {
    registry.addResourceHandler("swagger-ui.html")
        .addResourceLocations("classpath:/META-INF/resources/");

    registry.addResourceHandler("/webjars/**")
        .addResourceLocations("classpath:/META-INF/resources/webjars");
  }

  @Bean
  public Docket api() {
    return new Docket(DocumentationType.SWAGGER_2)
        .select()
        .apis(RequestHandlerSelectors.any())
        .paths(PathSelectors.ant("/api/**"))
        .build()
        .apiInfo(apiInfo());
  }

  private ApiInfo apiInfo() {
    return new ApiInfoBuilder()
        .title("제목")
        .description("설명")
	.contact(new Contact("이름", "홈페이지 URL", "Email"))
        .build();
  }
}

Spring-fox 는 오래전에 나온 라이브러리이고 2020년 이후로 업데이트가 멈췄다.

⇒ Spring Boot 2.6이상 버전에서 바로 적용이 안된다.

따라서, WebMvc Configuration 을 직접 건드려 설정해야한다.

• ResourceHandler 등록을 하기 위해 addResourceHandlers 메소드를 오버라이드해 Swagger UI 를 ResourceHandler로 등록해주어야 한다.

Docket

• Springfox 프레임워크의 기본 인터페이스가 될 빌더로 구성을 위한 여러가지 기본값, 방법을 제공
• select()로 ApiSelectorBuilder를 반환받아 사용할 수 있도록 한다.

apis

• 특정 위치의 API를 가져올 것인가에 대한 정의
• RequestHandlerSelectors.any() 인 경우 Spring Boot에서 기본적으로 제공하는 basic-error-controller로 API 문서로 만들어 준다.
• 특정 패키지만 적용하고 싶다면
  • RequestHandlerSelectors.basePackage(”com.example.demo.test”)와 같은 형식으로 지정하면 해당 패키지 하위에 있는 Controller 기준으로 만들어준다.

paths

• 특정 path만 필터링하여 문서를 만든다.
  
  

Spring-Doc 적용

Spring-fox는 WebMvc Configuration을 직접 건드려 Spring-doc를 사용

의존성 추가

implementation group: 'org.springdoc', name: 'springdoc-openapi-ui', version: '1.6.12'

SwaggerConfig.java

@Configuration
public class SwaggerConfig {

    @Bean
    public GroupedOpenApi publicApi() {
        return GroupedOpenApi.builder()
                .group("이름")
                .pathsToMatch("/api/**")
                .build();
    }
    @Bean
    public OpenAPI springShopOpenAPI() {
        return new OpenAPI()
                .info(new Info().title("제목")
                        .description("설명")
                        .version("v0.0.1");
    }
}

group

• group 이름 설정

pathsToMatch

• Swagger API 문서에 적을 주소를 작성 (path를 필터링)

OpenAPI

• Swagger API 문서 Customizing

Controller

@Tag(name = "users", description = "유저 API")
@RestController
@RequestMapping("/api/v1/users")
public class UserController {

  private final UserService userService;

  public UserController(UserService userService) {
    this.userService = userService;
  }

  @Operation(summary = "signup", description = "회원가입 요청")
  @ApiResponses({
      @ApiResponse(responseCode = "201", description = "OK", content = @Content(schema = @Schema(implementation = DataResponse.class))),
      @ApiResponse(responseCode = "400", description = "BAD REQUEST", content = @Content(schema = @Schema(implementation = ErrorResponse.class))),
      @ApiResponse(responseCode = "404", description = "NOT FOUND", content = @Content(schema = @Schema(implementation = ErrorResponse.class))),
      @ApiResponse(responseCode = "500", description = "INTERNAL SERVER ERROR", content = @Content(schema = @Schema(implementation = ErrorResponse.class)))
  })
  @PostMapping("")
  public ResponseEntity<DataResponse<UserResponse.UserSignupResponse>> signUp(@Validated @RequestBody UserRequest.SignUp signUpRequest) {
    
  }

@Tag

• API 그룹 설정을 위한 어노테이션
• name 속성으로 태그의 이름을 설정
• description 속성으로 태그에 대한 설명을 추가

@Operation

• api 상세 정보 설정을 위한 어노테이션
• summary 속성으로 API에 대한 간단한 설명
• description 속성으로 api에 대한 상세 설명을 추가
• responses, parameters 속성을 추가로 적용할 수 있다.

@ApiResponses

• 여러 개의 @ApiResponse 를 묶기 위한 어노테이션

@ApiResponse

• API의 response 설정을 위한 어노테이션
• responseCode 속성으로 HTTP 상태 코드 설정
• description 속성으로 response에 대한 설명 추가
• implementation에는 responseBody로 제공될 클래스 타입만 설정 가능

@Parameter

• API parameter 설정을 위한 어노테이션
• name 속성으로 파라미터 이름
• description으로 설명
• in으로 파라미터의 위치를 설정

Request, Response 객체

@Getter
public static class LoginRequest {
    @Schema(description = "아이디", defaultValue = "testId")
    public String id;
    @Schema(description = "비밀번호", defaultValue = "testPassword")
    public String password;
}
  
@Getter
@AllArgsConstructor
public static class LoginResponse {
    @Schema(description = "엑세스 토큰")
    private String accessToken;
    @Schema(description = "리프레시 토큰")
    private String refreshToken;
}

@Schema

• Request, Response 객체에 대한 설정을 위한 어노테이션
• description으로 설명 추가
• defaultValue로 기본으로 사용할 값 설정
• example 을 통해 예시 설정

참고 자료

https://www.baeldung.com/swagger-2-documentation-for-spring-rest-api

https://wildeveloperetrain.tistory.com/156

https://velog.io/@jeong-god/Spring-boot-Swagger-API-연동하기

https://chanos.tistory.com/entry/Spring-API-문서-자동화를-위한-Swagger-300-적용