Swagger 사용법

build.gradle 에 다음 의존성 추가

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

 

 

SecurityConfig 에 다음 사항 permitAll() 적용

new AntPathRequestMatcher("/swagger-ui/**"),
new AntPathRequestMatcher("/v3/api-docs/**"),
new AntPathRequestMatcher("/swagger-resources/**"),
new AntPathRequestMatcher("/swagger-ui.html"),
new AntPathRequestMatcher("/webjars/**")

 

 

JwtFilter 에 다음 사항을 화이트리스트에 적용

new HttpRequest(HttpMethod.GET, "/swagger-ui/**"),
new HttpRequest(HttpMethod.GET, "/v3/api-docs/**"),
new HttpRequest(HttpMethod.GET, "/swagger-resources/**"),
new HttpRequest(HttpMethod.GET, "/swagger-ui.html"),
new HttpRequest(HttpMethod.GET, "/webjars/**")

 

 

---

 

@Tag

⦁ API 그룹을 정의한다.

⦁ 위치 : 클래스

import io.swagger.v3.oas.annotations.tags.Tag;
import org.springframework.web.bind.annotation.*;

@RestController
@RequestMapping("/api/users")
@Tag(name = "User API", description = "사용자 관리 API")
public class UserController {
    @GetMapping("/{id}")
    public String getUser(@PathVariable Long id) {
        return "User ID: " + id;
    }
}

 

 

 

 

 

@Operation

⦁ 개별 엔드포인트마다 설명을 추가한다. ( 개별 엔드포인트란? ex. GET /api/users/{id} )

⦁ 위치 : 메서드

import io.swagger.v3.oas.annotations.Operation;
import org.springframework.web.bind.annotation.*;

@RestController
@RequestMapping("/api/users")
@Tag(name = "User API", description = "사용자 관리 API")
public class UserController {
    @GetMapping("/{id}")
    @Operation(summary = "사용자 조회", description = "사용자의 ID로 정보를 조회합니다.")
    public String getUser(@PathVariable Long id) {
        return "User ID: " + id;
    }
}

 

 

 

 

 

@Parameter

⦁ API 메서드 개별 파라미터를 설명한다.

⦁ 위치 : 메서드 파라미터

import io.swagger.v3.oas.annotations.Parameter;
import org.springframework.web.bind.annotation.*;

@RestController
@RequestMapping("/api/users")
@Tag(name = "User API", description = "사용자 관리 API")
public class UserController {
    @GetMapping("/{id}")
    @Operation(summary = "사용자 조회", description = "사용자의 ID로 정보를 조회합니다.")
    public String getUser(
        @Parameter(description = "조회할 사용자 ID", example = "1") @PathVariable Long id
    ) {
        return "User ID: " + id;
    }
}

 

 

 

 

@Schema

⦁ DTO 나 모델 객체를 설명한다.

⦁ 위치 : 클래스, 필드, 메서드

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

@Schema(description = "사용자 생성 요청 모델")
public class UserRequest {
    @Schema(description = "사용자의 이름", example = "홍길동")
    private String name;
    
    @Schema(description = "사용자의 이메일", example = "hong@domain.com")
    private String email;

    // Getter, Setter
}

 

 

 

 

@ApiResponse

⦁ API 메서드의 응답을 설명한다.

⦁ 위치 : 메서드

import io.swagger.v3.oas.annotations.Operation;
import io.swagger.v3.oas.annotations.responses.ApiResponse;
import org.springframework.web.bind.annotation.*;

@RestController
@RequestMapping("/api/users")
@Tag(name = "User API", description = "사용자 관리 API")
public class UserController {
    @GetMapping("/{id}")
    @Operation(summary = "사용자 조회", description = "사용자의 ID로 정보를 조회합니다.",
        responses = {
            @ApiResponse(responseCode = "200", description = "성공적으로 조회됨"),
            @ApiResponse(responseCode = "404", description = "사용자를 찾을 수 없음")
        }
    )
    public String getUser(@PathVariable Long id) {
        return "User ID: " + id;
    }
}

 

 

 

참고 깃허브 : https://github.com/woowacourse-teams/2024-touroot/blob/develop/be/backend/src/main/java/kr/touroot/member/controller/MemberController.java