Swagger란?

: 서버로 요청되는 URL 리스트를 HTML화면으로 문서화 및 테스트 할 수 있는 라이브러리이다.
✔️ 즉, Swagger는 API 문서 이다.

Swagger의 어노테이션

1. @ApiOperation = Method 설명

@ApiOperation 으로 해당 Controller 안의 method의 설명을 추가할 수 있다.

@ApiOperation(value = "해당 API의 이름", notes = "해당 API의 설명")

2. @ApilmplicitParam = Request Parameter 설명

@ApilmplicitParam 어노테이션으로 해당 API Method 호출에 필요한 Parameter들의 설명을 추가할 수 있다.

@ApiImplicitParam(
        name = "id"
        , value = "사용자 아이디"
        , required = true
        , dataType = "string"
        , paramType = "path"
        , defaultValue = "None")

• dataType, paramType, required의 경우 해당 name의 정보가 자동으로 채워지므로 생략 할 수 있다.
• paramType의 경우 @RequestParam은 query를 @PathVariable은 path를 명시해주면 된다.
• 해당 Method의 Parameter가 복수일 경우, @ApilmplicitParams로 @ApilmplicitParam을 여러 개 사용할 수 있다.
  Ex) @ApilmplicitParams 예시

	@ApiImplicitParams(
        {
            @ApiImplicitParam(
                name = "id"
                , value = "자격증 아이디"
                , required = true
                , dataType = "string"
                , paramType = "path"
                , defaultValue = "None"
            )
        ,
            @ApiImplicitParam(
                name = "fields"
                , value = "응답 필드 종류"
                , required = false
                , dataType = "string"
                , paramType = "query"
                , defaultValue = ""
            )
        })

3. @ApiResponse = Response 설명

@ApiResponse 어노테이션으로 해당 Method의 Response에 대한 설명을 작성할 수 있다.

    @ApiResponse(
        code = 200
        , message = "성공입니다."
    )

• 여러 개의 Response에 대한 설명을 추가 하고 싶다면, @ApiResponses를 사용하면 된다.

    @ApiResponses({
        @ApiResponse(code = 200, message = "성공입니다.")
        , @ApiResponse(code = 400, message = "접근이 올바르지 않습니다.")
    })

4. Default Response Message 삭제

기본적으로 보이는 응답 메세지를 삭제하고 싶다면, Swagger Config의 Docket에 useDefaultResponseMessages(false)를 설정해주면 된다.
그럼 @ApiResponse로 설명하지 않은401, 403, 404 응답들이 사라진다.

5. @ApiParam = DTO field 설명

@ApiParam 어노테이션으로 DTO의 field에 대한 설명을 추가할 수 있다.

@ApiParam(value = "사용자 ID", required = true)
private String id;

@ApiParam(value = "사용자 이름")
private String name;

🐸 Controller에서 Parameter들에 바로 적용할 수도 있지만 추천하지는 않음.

    @GetMapping("/debates/{id}")
    public String getDebate(@ApiParam(value = "토론 ID") @PathVariable(name = "id") String id) {
        return "debate";
    }

---

참조 :
https://velog.io/@gillog/Swagger-UI-Annotation-%EC%84%A4%EB%AA%85