[Spring] Swagger 적용하기

늘보·2025년 2월 3일

Spring Swagger

Spring

목록 보기

4/24

Swagger(스웨거)

Open Api Specification(OAS)를 위한 프레임 워크이다.
Swagger를 사용하면 Web API가 수정되었을 때 문서가 자동으로 갱신된다.

OAS는 RESTful 웹 서비스를 약속된 규칙에 맞게 API 스펙을 JSON과 YAML 형식으로 표현한다. ➡︎ 이를 통해 추가 문서 없이 서비스를 이해할 수 있다.

개발 환경

SpringBoot 3.4.2
Java 17

build.gradle 의존성 추가

💡 OpenAPI 3.0부터는 SpringFox를 지원하지 않는다. 따라서, SprirngDoc로 변경하여 진행한다.
//Swagger
    implementation 'org.springdoc:springdoc-openapi-starter-webmvc-ui:2.0.4'

SwaggerConfig 설정

💡패키지 생성 후 Config 작성

import io.swagger.v3.oas.models.OpenAPI;
import io.swagger.v3.oas.models.info.Info;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;

@Configuration
public class SwaggerConfig {

   @Bean
   public OpenAPI openAPI() {
       Info info = new Info()
               .version("v1.0") //버전
               .title("일정 관리 API") //이름
               .description("일정 관리 프로젝트 API"); //설명
       return new OpenAPI()
               .info(info);
   }
}

Controller & ControllerDocs

ControllerDocs

UserControllerDocs : 인터페이스

@Tag(name = "사용자 관리", description = "사용자 관리 API입니다.")
public interface UserControllerDocs {

    @Operation(summary = "사용자 등록", description = "작성자명, 비밀번호, 이메일을 입력받아 사용자를 등록합니다. ")
    @ApiResponses(value = {
            @ApiResponse(responseCode = "200", description = "일정이 성공적으로 등록되었습니다."),
            @ApiResponse(responseCode = "400", description = "작성자명, 비밀번호 미입력으로 일정 등록에 실패하였습니다.")
    })
    public ResponseEntity<UserResponseDto> createUser(
            @RequestBody UserRequestDto dto);

    @Operation(summary = "사용자 수정", description = "사용자의 `작성자명(author)`만 수정 가능하며, 올바른 비밀번호 입력 시 사용자 수정이 가능합니다.")
    public ResponseEntity<UserResponseDto> updateUser(
            @Parameter(description = "수정할 사용자 ID")
            @PathVariable Long userId,

            @RequestBody UserRequestDto dto
    );
}

Controller

UserController : 구현체

public class UserController implements UserControllerDocs {

    private final UserService userService;

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

    @Override
    @PostMapping
    public ResponseEntity<UserResponseDto> createUser(@RequestBody UserRequestDto dto) {
        return new ResponseEntity<>(userService.createUser(dto), HttpStatus.CREATED);
    }

    @Override
    @PatchMapping("/{userId}")
    public ResponseEntity<UserResponseDto> updateUser(
            @PathVariable Long userId,
            @RequestBody UserRequestDto dto
    ) {
        return new ResponseEntity<>(userService.updateUser(userId, dto), HttpStatus.OK);
    }
}