[Spring] Swagger UI 적용

🌱 Swagger UI

Swagger UI는 RESTful API를 문서화하고 시각적으로 표현하기 위한 도구다.

 

API의 엔드포인트, 요청 및 응답 형식 등을 사용자에게 쉽게 이해할 수 있는 형태로 보여준다. 

 

🌱 Swagger UI 장점

1. 자동 문서화: Swagger UI는 API 코드에 주석을 추가하거나 Swagger Annotation을 사용하여 자동으로 API 문서를 생성한다. 이를 통해 개발자들은 코드 변경 시 문서도 함께 업데이트할 수 있다.
2. 인터랙티브: Swagger UI는 사용자가 API를 직접 테스트할 수 있는 인터페이스를 제공한다. 사용자는 요청을 보내고 응답을 확인할 수 있어 API의 동작을 쉽게 이해할 수 있다.
3. 시각적 표현: API의 엔드포인트, 요청 및 응답 모델을 시각적으로 표시하여 개발자와 비개발자 모두가 쉽게 이해할 수 있도록 도와준다.
4. 다양한 지원: Swagger는 여러 프로그래밍 언어와 프레임워크를 지원하며, Spring Boot와 같은 Java 기반의 웹 프레임워크와도 쉽게 통합할 수 있다.

---

🌱 사용법

build.gradle

// Swagger UI
implementation 'org.springdoc:springdoc-openapi-starter-webmvc-ui:2.1.0'

 

build.gradle 에 의존성을 추가해준다.

---

SwaggerConfig

@Configuration
public class SwaggerConfig {
    @Bean
    public OpenAPI openAPI() {
        String jwt = "JWT";
        SecurityRequirement securityRequirement = new SecurityRequirement().addList(jwt);
        Components components = new Components().addSecuritySchemes(jwt, new SecurityScheme()
                .name(jwt)
                .type(SecurityScheme.Type.HTTP)
                .scheme("bearer")
                .bearerFormat("JWT")
        );
        return new OpenAPI()
                .components(new Components())
                .info(apiInfo())
                .addSecurityItem(securityRequirement)
                .components(components);
    }

    private Info apiInfo() {
        return new Info()
                .title("싹틔움") // API의 제목
                .description("싹틔움 프로젝트 API 명세 및 테스트") // API에 대한 설명
                .version("1.0.0"); // API의 버전
    }
}

 

Swagger UI 를 사용하기 위한 Config 파일을 만들어준다.

---

Controller

@RestController
@RequiredArgsConstructor
@Tag(name = "회원가입/로그인 관리기능", description = "회원가입과 로그인할 수 있는 기능")
public class AuthController {

    private final AuthService authService;

    @PostMapping("/v1/auth/signup")
    @Operation(summary = "회원가입", description = "회원가입하는 API")
    @ApiResponse(responseCode = "200", description = "요청이 성공적으로 처리되었습니다.")
    public ResponseEntity<CommonResponse<SignupResponseDto>> signup(@Valid
                                                                    @RequestBody
                                                                    @Parameter(description = "회원정보 입력")
                                                                    SignupRequestDto signupRequestDto) {
        return ResponseEntity.ok(CommonResponse.success(authService.signup(signupRequestDto)));
    }

 

@Tag(name = "회원가입/로그인 관리기능", description = "회원가입과 로그인할 수 있는 기능")

 

Class 위에 @Tag 를 달아서 해당 Controller Class 에 대한 이름과 설명을 작성해준다.

 

@Operation(summary = "회원가입", description = "회원가입하는 API")
@ApiResponse(responseCode = "200", description = "요청이 성공적으로 처리되었습니다.")

 

Controller 의 메서드 위에 Annotation 을 달아준다.

@Operation 는 해당 메서드의 이름과 설명을 달아준다.

@ApiResponse 는 성공 또는 실패의 경우 어떻게 묘사될 것인지 적어준다. 위 코드에서는 상태코드 200 이 반환되는 경우만 설정해줬는데, 실패의 경우도 추가로 적어줄 수 있다.

 

@RequestBody
@Parameter(description = "회원정보 입력")
SignupRequestDto signupRequestDto) {

 

Dto 의 경우 @Parameter 를 달아서 해당 Dto 에 대한 이름을 작성해준다.

 

SignupRequestDto

@Getter
@NoArgsConstructor
@AllArgsConstructor
public class SignupRequestDto {

    @NotBlank
    @Email
    @Schema(description = "이메일", example = "email@gmail.com")
    private String email;

 

해당 Dto 안에서 각 각의 필드 위에 @Schema 를 달아서 해당 필드의 이름과 예시를 작성해준다.

 

@PathVariable
@Parameter(description = "요청할 식물도감 Id", example = "1")
Long id

 

만약 이처럼 Dto 가 아니라 @PathVariavle 로 데이터를 받아온다면 직접 이름과 예시를 달아줄 수 있다.