[JAVA] swagger로 API문서 자동화

swagger란 개발한 REST API를 편리하게 문서화해주고, 이를 통해서 관리 및 제3의 사용자가 편리하게 API를 호출해보고 테스트할 수 있는 프로젝트이다

 

spring boot에서는 간단하게 springfox-boot-starter를 gradle dependencies에 추가해서 사용할 수 있다

 

다만, 주의할 점은 운영환경과 같은 외부에 노출되면 안 되는 곳에는 사용할 때 주의해야 한다

 

Annotation	설명
@Api	클래스를 스웨거의 리소스로 표시
@ApiOperation	특정 경로의 오퍼레이션 HTTP 메소드 설명
@ApiParam	오퍼레이션 파라미터에 메타 데이터 설명
@ApiResponse	오퍼레이션의 응답 지정
@ApiModeProperty	모델의 속성 데이터를 설명
@ApiImplicitParam	메소드 단위의 오퍼레이션 파라미터를 설명
@ApiImplicitParams

간단하게 swagger에서 대표적으로 쓰는 Annotation의 대한 설명이다

 

dependencies {
    implementation 'org.springframework.boot:spring-boot-starter-web'
    compileOnly 'org.projectlombok:lombok'
    annotationProcessor 'org.projectlombok:lombok'
    testImplementation 'org.springframework.boot:spring-boot-starter-test'
    // https://mvnrepository.com/artifact/io.springfox/springfox-boot-starter
    implementation group: 'io.springfox', name: 'springfox-boot-starter', version: '3.0.0'

}

gradle dependencies에 springfox-boot-starter를 추가해주면 swagger를 쓸 준비가 끝났다

 

예전 버전에서는 따로 설정할 게 있었지만 springfox-boot-starter에서는 따로 설정이 필요 없게 되었다

 

이제 소스를 통해 어떻게 사용되는지 알아볼 것이다

 

controller 패키지를 하나 만들고 그 안에 ApiController 클래스를 만든 뒤 아래와 같이 소스를 작성한다

import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RestController;

@RestController
@RequestMapping("/api")
public class ApiController {

    @GetMapping("/hello")
    public String hello() {
        return "Hello";
    }
}

그다음 서버를 실행 후 localhost:8080/swagger-ui/ 로 접속해 보면 아래와 같이 우리가 만든 api를 확인할 수 있다

여기서 swagger-ui 뒤에 슬래쉬는 꼭 붙여 줘야 한다

 

Response body에 우리가 보낸 Hello 가 정상적으로 찍히는 걸 확인할 수 있다

 

그럼 스웨거의 여러 기능들을 확인해 보기 위해 dto 패키지를 만들고 User 클래스를 생성한 뒤 아래와 같이 작성한다

import io.swagger.annotations.ApiModelProperty;
import lombok.AllArgsConstructor;
import lombok.Data;
import lombok.NoArgsConstructor;

@Data
@NoArgsConstructor
@AllArgsConstructor
public class User {
    @ApiModelProperty(value = "유저 네임", example = "Kim", required = true)
    private String name;
    @ApiModelProperty(value = "유저 나이", example = "20", required = true)
    private int age;
}

그리고 만들어 뒀던 ApiController를 수정해 준다

import com.example.swagger.dto.User;
import io.swagger.annotations.*;
import org.springframework.web.bind.annotation.*;

@Api(tags = {"API 정보를 제공하는 Controller"})
@RestController
@RequestMapping("/api")
public class ApiController {

    @GetMapping("/hello")
    public String hello() {
        return "Hello";
    }

    @ApiImplicitParams({
            @ApiImplicitParam(name = "y", value = "y 값", required = true, paramType = "query", dataType = "int"),
            @ApiImplicitParam(name = "x", value = "x 값", required = true, paramType = "path", dataType = "int"),
    })
    @GetMapping("/plus/{x}")
    public int plus(@RequestParam int y, @PathVariable int x) {
        return x + y;
    }

    @ApiResponse(code = 502, message = "유저의 나이가 7살 이하일 때")
    @ApiOperation(value = "유저의 이름과 나이를 반환하는 메소드")
    @GetMapping("/user")
    public User userGet(User user) {
        return user;
    }

    @PostMapping("/user")
    public User userPost(@RequestBody User user) {
        return user;
    }
}

다시 서버를 재실행시켜 swagger 문서를 확인해 보면 알아보기 쉽게 설명이 들어가 있는 것을 확인해 볼 수 있다

 

위에 swagger annotation 설명을 보면서 하나하나씩 직접 확인해 보면 어떤 부분이 어떻게 적용되는지 쉽게 확인할 수 있다