[Spring] Swagger를 이용한 REST API 문서화를 해보자!

| REST API 문서화?

---

FE 개발자의 경우 화면과 로직에 집중하고,

BE 개발자가 만든 무서 API를 보며 데이터 처리를 하게 되는데...

이때 개발 상황의 변화에 따른 API의 추가 or 변경할 때마다

문서에 적용하는 불편함을 해결하기 위해 Swagger를 사용

Swagger ??

는 API 목록을 웹에서 확인 및 테스트할 수 있게 도와주는 Library이다.

Controller에 정의된 모든 URL을 확인할 뿐만 아니라

목록, 명세 및 설명, 테스트까지 가능하다.

|| Swagger 적용

---

Swagger를 사용하기 위해

먼저 pom.xml 에 

springfox-swagger2

springfox-swagger-ui

dependency를 추가해주어야 한다.

/pom.xml

1 2 3 4 5 6 7 8 9 10 11 12

<!-- https://mvnrepository.com/artifact/io.springfox/springfox-swagger2 -->         <dependency>             <groupId>io.springfox</groupId>             <artifactId>springfox-swagger2</artifactId>             <version>2.9.2</version>         </dependency>         <!-- https://mvnrepository.com/artifact/io.springfox/springfox-swagger-ui -->         <dependency>             <groupId>io.springfox</groupId>             <artifactId>springfox-swagger-ui</artifactId>             <version>2.9.2</version>         </dependency> Colored by Color Scripter

cs

---

다음으로 

SwaggerConfiguration 파일을 작성해야 한다.

설정 확인 방법은 아래와 같다.

Swagger 설정 확인

http://localhost:8000/{your-app-root}/v2/api-docs

example : http://localhost:8000/web/v2/api-docs?group=V1

Swagger-UI 확인

http://localhost:8080/{your-app-root}/swagger-ui.html

example : http://localhost:8000/web/swagger-ui.html

/src/main/java/com/cristoval/web/SwaggerConfiguration.java

@Configuration
@EnableSwagger2
public class SwaggerConfiguration {
 
    private String version = "V1";
    private String title = "Cristoval GuestBook API " + version;
    
    @Bean
    public Docket api() {
        List<ResponseMessage> responseMessages = new ArrayList<ResponseMessage>();
        responseMessages.add(new ResponseMessageBuilder().code(200).message("OK !!!").build());
        responseMessages.add(new ResponseMessageBuilder().code(500).message("서버 문제 발생 !!!").responseModel(new ModelRef("Error")).build());
        responseMessages.add(new ResponseMessageBuilder().code(404).message("페이지를 찾을 수 없습니다 !!!").build());
        
        return new Docket(DocumentationType.SWAGGER_2).apiInfo(apiInfo()).groupName(version).select()
                    .apis(RequestHandlerSelectors.basePackage("com.cristoval.web.controller"))
                    .paths(postPaths()).build()
                    .useDefaultResponseMessages(false) // responseMessages 설정 적용
                    .globalResponseMessage(RequestMethod.GET,responseMessages);
    }
    
    private Predicate<String> postPaths() {
//      return PathSelectors.any(); // 모든 경로를 api 문서로 만들경우
//      return or(regex("/admin/.*"), regex("/user/.*"));  // 일부 경로를 api 문서로 만들 경우
        return regex("/admin/.*");
    }
 
    private ApiInfo apiInfo() {
        return new ApiInfoBuilder().title(title)
                .description("<h3>CRISTOVAL API Reference for Developers</h3>Swagger를 이용한 GuestBook API<br><img src=\"imgName.png\">") 
                .contact(new Contact("CRISTOVAL", "https://cistoval.com", "cristoval@gmail.com"))
                .license("CRISTOVAL License")
                .licenseUrl("https://www.cristoval.com/etc/webPrivacy.jsp")
                .version("1.0").build();
    }
}
 

line 10~13) responseMessage들을 추가할 수 있다.

line 15~19) SWAGGER Docket에 

 api 정보를 담은 apiInfo()의 결과와 변수로 선언한 version 정보,

 다룰 Controller들이 있는 package 정보

 api 문서로 만들 경로가 담긴 PostPaths()의 결과

 responseMessages 설정을 적용한 후 return 해준다.

+++

다른 Version도 API 문서로 만들고 싶다면,

아래와 같이 새로운 메서드를 생성해서 추가해주면 된다.

    @Bean
    public Docket api2() {
        version = "V2";
        List<ResponseMessage> responseMessages = new ArrayList<ResponseMessage>();
        responseMessages.add(new ResponseMessageBuilder().code(200).message("OK !!!").build());
        responseMessages.add(new ResponseMessageBuilder().code(500).message("서버 문제 발생 !!!").responseModel(new ModelRef("Error")).build());
        responseMessages.add(new ResponseMessageBuilder().code(404).message("페이지를 찾을 수 없습니다 !!!").build());
        
        return new Docket(DocumentationType.SWAGGER_2).apiInfo(apiInfo2()).groupName(version).select()
                    .apis(RequestHandlerSelectors.basePackage("com.cristoval.web.controller"))
                    .paths(postPaths()).build()
                    .useDefaultResponseMessages(false) // responseMessages 설정 적용
                    .globalResponseMessage(RequestMethod.GET,responseMessages);
    }
    
    
    private ApiInfo apiInfo2() {
        return new ApiInfoBuilder().title(title)
                .description("<h3>CRISTOVAL API Reference for Developers</h3>Swagger를 이용한 GuestBook API<br><img src=\"imgName.png\">") 
                .contact(new Contact("CRISTOVAL", "https://cistoval.com", "cristoval@gmail.com"))
                .license("CRISTOVAL License")
                .licenseUrl("https://www.cristoval.com/etc/webPrivacy.jsp")
                .version("2.0").build();
    }

---

---

---

|| Controller, DTO

---

Swagger가 적용될 Controller에 메서드 설명, 상세설명 등을 적용해줄 수 있다.

Api를 적용하기 위해 @Api annotation에 Controller 이름을 작성해준다.

@ApiOperation에는 메서드 설명과, 상세 설명을 작성할 수 있다. 설명에는 html 적용도 가능하다!

@ApiResponses에는 각 메서드에 해당하는 responseMessage를 적용할 수 있다.

@ApiParam는 파라미터의 설명을 적용해준다. required = true 속성 설정도 가능하다. 

/src/main/java/com/cristoval/web/controller/AdminController.java

@RestController
@Api("Admin Controller API V1")
@RequestMapping("/admin")
public class AdminController {
 
    @Autowired
    private UserService userService;
    // 메서드 설명, 메서드 상세 설명, html 적용도 가능. 
    @ApiOperation(value = "회원 목록", notes = "<big>회원 전체 목록</big>을 반환한다.")
    @GetMapping(value = "/user", headers = { "Content-type=application/json" })
    public List<MemberDto> userList() {
        return userService.userList();
    }
    
    @ApiOperation(value = "회원 등록", notes = "<strong>회원의 정보</strong>를 입력받아 등록한다.")
    // 각 메서드에 responseMessage를 
    @ApiResponses({
        @ApiResponse(code = 200, message = "회원 목록 OK!!!"),
        @ApiResponse(code = 404, message = "서버 문제 발생!!!"),
        @ApiResponse(code = 500, message = "페이지를 찾을 수 없어!!!")
    })
    @PostMapping(value = "/user", headers = { "Content-type=application/json" })
    // required = true 속성 설정
    public List<MemberDto> userRegister(@RequestBody @ApiParam(value = "회원 한 명의 정보를 갖는 객체", required = true) MemberDto memberDto) {
        userService.userRegister(memberDto);
        return userService.userList();
    }
    
    @ApiOperation(value = "회원 정보", notes = "회원 한 명에 대한 정보이다.")
    @GetMapping(value = "/user/{userid}", headers = { "Content-type=application/json" })
    public MemberDto userInfo(@PathVariable @ApiParam(value = "검색할 회원의 아이디") String userid) {
        return userService.userInfo(userid);
    }
    
    @ApiOperation(value = "회원 정보 수정", notes = "회원 정보를 수정한다.")
    @PutMapping(value = "/user", headers = { "Content-type=application/json" })
    public List<MemberDto> userModify(@RequestBody @ApiParam(value = "수정할 회원 정보", required = true) MemberDto memberDto) {
        userService.userModify(memberDto);
        return userService.userList();
    }
    
    @ApiOperation(value = "회원 정보 삭제", notes = "회원 정보를 삭제한다.")
    @DeleteMapping(value = "/user/{userid}", headers = { "Content-type=application/json" })
    public List<MemberDto> userDelete(@PathVariable @ApiParam(value = "삭제할 회원 정보", required = true) String userid) {
        userService.userDelete(userid);
        return userService.userList();
    }
    
}
 

---

Swagger가 적용될 Model에도 DTO에 대한 정보를 적용해줄 수 있다.

@ApiModel에는 Model에 대한 설명, 상세 설명,

@ApiModelProperty에는 속성에 대한 설명

/src/main/java/com/cristoval/web/model/MemberDto.java

@ApiModel(value = "회원 정보", description = "아이디, 이름, 비밀번호, 이메일, 주소, 가입날짜를 가진 Domain Class")
public class MemberDto {
 
    @ApiModelProperty(value = "아이디")
    private String userid;
    @ApiModelProperty(value = "이름")
    private String username;
    @ApiModelProperty(value = "비밀번호")
    private String userpwd;
    @ApiModelProperty(value = "이메일")
    private String email;
    @ApiModelProperty(value = "주소")
    private String address;
    @ApiModelProperty(value = "가입일")
    private String joindate;
 
    // ...
 
}
 

|| 결과 화면

---

> 초기 화면

> Controller와 Models 정보

> API TEST

Try it out 버튼을 누르고 Execute 해보면서 API를 테스트할 수 있다.