Cursor + SpringBoot 개발설정3 + openapi

Springdoc이 Springfox보다 공식 문서도 잘되어 있고 꾸준히 업데이트 된다고 하여 이번에는 Springdoc로 설정하자.

 

개발환경 설정

의존성 추가

• build.gradle (lombok 및 springdoc-openapi 추가)

...

dependencies {
    ...
    
    implementation 'org.springdoc:springdoc-openapi-starter-webmvc-ui:2.3.0'

	compileOnly 'org.projectlombok:lombok'
	annotationProcessor 'org.projectlombok:lombok'
}

...

 

openAPI Config 파일 추가

• OpenApiConfig

package com.test.spring_boot_demo.config;

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

import org.springdoc.core.models.GroupedOpenApi;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;

@Configuration
public class OpenApiConfig {

  @Bean
  public OpenAPI openAPI() {
    Info info = new Info()
        .title("Spring API 문서")
        .version("v1.0")
        .description("Spring Boot API 설명 문서")
        .contact(new Contact()
            .name("개발자")
            .email("developer@example.com"));

    return new OpenAPI()
        .info(info);
  }

  @Bean
  public GroupedOpenApi group1() {
    return GroupedOpenApi.builder()
        .group("1. Version 1")
        .pathsToMatch("/v1/**")
        .build();
  }

}

 

Controller API 파일 및 Model 추가

• UserController

package com.test.spring_boot_demo.controller.v1;

import com.test.spring_boot_demo.model.User;
import io.swagger.v3.oas.annotations.Operation;
import io.swagger.v3.oas.annotations.Parameter;
import io.swagger.v3.oas.annotations.tags.Tag;
import org.springframework.web.bind.annotation.*;

import java.util.ArrayList;
import java.util.List;

@RestController
@RequestMapping("/v1/api/users")
@Tag(name = "User", description = "사용자 API")
public class UserController {

    @Operation(summary = "사용자 목록 조회", description = "모든 사용자 정보를 조회합니다.")
    @GetMapping
    public List<User> getAllUsers() {
        return new ArrayList<>();
    }

    @Operation(summary = "사용자 조회", description = "특정 사용자의 정보를 조회합니다.")
    @GetMapping("/{id}")
    public User getUser(
            @Parameter(description = "사용자 ID") @PathVariable Long id) {
        return new User();
    }

    @Operation(summary = "사용자 등록", description = "새로운 사용자를 등록합니다.")
    @PostMapping
    public User createUser(
            @Parameter(description = "사용자 정보") @RequestBody User user) {
        return user;
    }

    @Operation(summary = "사용자 정보 수정", description = "기존 사용자의 정보를 수정합니다.")
    @PutMapping("/{id}")
    public User updateUser(
            @Parameter(description = "사용자 ID") @PathVariable Long id,
            @Parameter(description = "수정할 사용자 정보") @RequestBody User user) {
        return user;
    }

    @Operation(summary = "사용자 삭제", description = "특정 사용자를 삭제합니다.")
    @DeleteMapping("/{id}")
    public void deleteUser(
            @Parameter(description = "사용자 ID") @PathVariable Long id) {
    }
}

 

• User

package com.test.spring_boot_demo.model;

import io.swagger.v3.oas.annotations.media.Schema;
import lombok.Data;

@Data
@Schema(description = "사용자 정보")
public class User {

  @Schema(description = "사용자 ID", example = "1")
  private Long id;

  @Schema(description = "사용자 이름", example = "홍길동")
  private String name;

  @Schema(description = "이메일", example = "hong@example.com")
  private String email;
}

 

application 환경 설정

• application.yml (application.properties를 삭제하고 yml파일 생성)

spring:
  application:
    name: spring-boot-api

springdoc:
  swagger-ui:
    enabled: true
    path: /swagger-ui.html
    tags-sorter: alpha
    operations-sorter: alpha
    show-extensions: true

 

실행 및 확인

실행

 

확인

• http://localhost:8080/swagger-ui.html