스프링에서 swagger를 사용해 봤다

스프링 swagger 적용기

• 스프링에서 swagger를 적용하기 위해 여러 문제를 경험 했다.
• 과거에는 스프링에 swagger ui를 적용하기위해 springfox라는것을 사용했다고한다.
• 하지만 최근에는 업데이트를 종료 했으며 springdoc이라는것이 이것을 대체한다.

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

• 간단하게 다음과 같은 의존을 주입하고
• localhost:8080/swagger-ui/index.html 로 접속하면
•  

• 다음과 같은 화면을 볼수 있습니다.

@Tag 애너테이션

• @Tag 애너테이션을 사용하면 api의 태그를 설정 할수 있습니다.

@RestController
@AllArgsConstructor
@Tag(name = "카테고리 API" , description = "카테고리 API 입니다.")
public class CategoryController {

• 다음과 같이 api의 태그명을 바꿀수 있습니다.
• 과거 버전에서는 @Api를 사용하는 것을 볼 수있는데 이는 deprecated 되었다고 합니다.

@Operation 애너테이션

• @Operation 애너테이션은 각 메서드의 정보를 제공할 수있습니다.

@Operation(summary = "카테고리 id로 카테고리를 가져올 수 있습니다."
            , description = "url상에 /api/category/카테고리 아이디 형식으로 카테고리를 가져옵니다.")
    @ApiResponses(value = {
            @ApiResponse(responseCode = "200", description = "카테고리 요청 성공")
    })
    @GetMapping("/api/category/{categoryId}")
    public ResponseEntity<Category> getCategoryById(@PathVariable(name = "categoryId") Long categoryId){
        Category category = categoryService.findCategoryById(categoryId);
        return ResponseEntity.ok(category);
    }

• @ApiResponse 애너테이션은 응답에 대한 응답코드와 설명을 작성할 수 있습니다,
• @parameter로 해당 파라미터의 설명을 기술 할 수 있습니다.

 @GetMapping("/api/category/{categoryId}")
    public ResponseEntity<Category> getCategoryById(@Parameter(description = "카테고리의 아이디 값 (Long)") @PathVariable(name = "categoryId" ) Long categoryId){
        Category category = categoryService.findCategoryById(categoryId);
        return ResponseEntity.ok(category);
    }

requestBody 부분 예제 만들기

@Operation(summary = "카테고리를 추가합니다."
            , description = "요청의 body에 name: 을 설정하면 해당 카테고리를 추가합니다.")
    @ApiResponses(value = {
            @ApiResponse(responseCode = "200", description = "카테고리 요청 성공"),
            @ApiResponse(responseCode = "404", description = "카테고리 찾을 수 없음")
    })
    @PostMapping("/api/category")
    public ResponseEntity<Category> addCategory(@RequestBody CategoryDTO categoryDTO){
            Category category = categoryService.createCategory(categoryDTO.getName());

            return ResponseEntity.ok(category);
    }

• @RequestBody 애너테이션으로 dto를 받은 후

package com.booksajo.bookPanda.category.DTO;

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

@Schema(description = "카테고리 요청 DTO")
@Data
public class CategoryDTO {

    @Schema(description = "Id" , defaultValue = "80")
    private Long id;

    @Schema(description = "카테고리 이름" , defaultValue = "신문")
    private String name;
}

• 해당 dto에서는 @Schema 를 사용해 예제와 설명을 넣을 수 있습니다.

응답 리스트로 표현 하기

@Operation(summary = "카테고리를 모두 가져옵니다."
            , description = "카테고리를 모두 가져옵니다.")

    @ApiResponses(
            value = {
                    @ApiResponse(
                            content = {
                                    @Content(
                                            mediaType = "application/json",
                                            array= @ArraySchema(schema = @Schema(implementation = Category.class))
                                    )
                            }
                    )
            }
    )
    @GetMapping("/api/category")
    public ResponseEntity<List<Category>> getAllCategory(){
        List<Category> categories = categoryService.findAllCategory();
        return ResponseEntity.ok(categories);
    }

 

 

• 응답이 리스트(배열)의 형태로 나타난다.