Swagger

Swagger란?

• 개발한 Rest API를 편리하게 문서화해주는 프로젝트
• 관리 및 제 3자의 사용자가 편리하게 호출해보고 테스트할수 있게 해준다.

※ 주의점 : 운영환경과 같은 외부에 노출되면 안되는 곳에서 사용할땐 주의해야한다.

설치 방법

• xml

<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-boot-starter</artifactId>
    <version>3.0.0</version>
</dependency>

• gradle

implementation("io.springfox:springfox-boot-starter:3.0.0")

Swagger 제공 어노테이션

• @Api
  • 클래스를 스웨거의 리소스로 표시
  • 사용 예시

/*
    [루트 주소]/swagger-ui/index.html에서
    해당 컨트롤러 클래스의 이름이 REST API CONTROLLER로 보인다. 
*/
@Api(tags = {"REST API CONTROLLER"})

• @ApiOperation
  • 특정 경로의 오퍼레이션 HTTP 메소드 설명
  • 사용 예시

/*
    ● @ApiOperation 없는 경우
        ● 메소드명
    ● @ApiOperation 있는 경우
        ● hello method
        ● note는 /swagger-ui/index.html에서 해당 메소드 클릭시 보이는 주석을 설정한다.
*/
@ApiOperation(value = "hello method", notes = "기본적인 인사 GET API")

• @ApiParam
  • 메소드의 파라미터에 대한 메타 데이터 설명 (Controller의 메소드의 파라미터에서 사용)
  • 사용 예시

/*
    ● @ApiParam 없는 경우
        ● name - name
    ● @ApiParam 있는 경우
        ● name - 사용자 이름
*/
@ApiParam(value = "사용자 이름") String name

• @ApiResponse
  • 메소드의 응답 지정
  • 사용 예시

@ApiResponse(code = 404, message = "not found")

• @ApiModelProperty
  • 모델의 속성 데이터를 설명 (VO의 필드에서 사용)
  • 사용 예시

/*
    ● @ApiModelProperty이 없는 경우
        ● name - name
    ● @ApiModelProperty이 있는 경우
        ● name - 사용자 이름
*/
/*
    ● value
        ● 해당 필드에 대한 설명
    ● example
        ● /swagger-ui/index.html에서
            해당 메소드의 Responses의 Example Value 항목에서 보일 예시 값
    ● required
        ● 필수 여부
*/
@ApiModelProperty(value = "사용자 이름", example = "steve")

• @ApiImplicitParam
  • 메소드 단위의 오퍼레이션 파라미터를 설명
• @APiImplicitParams
  • @ApiImplicitParam의 배열을 지정
• @ApiImplicitParam와 @ApiImplicitParams의 예시 (Controller의 메소드 위에 명시)
  • name
    • 파라미터의 변수명을 의미
  • value
    • 해당 파라미터에 대한 설명
  • required
    • 필수 여부
  • dataType
    • 해당 파라미터의 데이터 타입

@ApiImplicitParams({  
    @ApiImplicitParam(name="name", value="사용자 이름"),  
    @ApiImplicitParam(name="age", value="사용자 나이")  
})

기본 사용법

1. 해당 프로젝트를 실행한다.
2. 브라우저를 키고 [도메인]/swagger-ui/index.html를 입력하여 결과물을 확인한다.

※ 예전에는 @SpringBootApplication Class에
@EnableSwagger2를 추가해야 했으나
현재는 추가하지 않아도 자동적으로 모든 컨트롤러에 Swagger가 적용된다. (일정 버전 이상부터)