Swagger
- Swagger란 개발한 REST API를 편리하게 문서화 해주고, 이를 통해 관리 및 제 3의 사용자가 편리하게 API를 호출해보고 테스트 할 수 있도록 해주는 프레임 워크이다.
- Spring Boot에서는 간단하게 springfox-boot-starter를 gradle dependencies에 추가하는 것으로 사용할 수 있다.
- 운영환경과 같이 외부에 노출되면 안되는 곳에는 사용할 때 주의 해야 한다.
Swagger Annotation
- Api
- 클래스를 Swagger의 리소스로 표시
- ApiOperation
- 특정 경로의 오퍼레이 HTTP Method 설명
- ApiParam
- 오퍼레이션 파라미터에 메타 데이터 설명
- ApiResponse
- 오퍼레이션의 응답 지정
- ApiModelProperty
- 모델의 속성 데이터를 설명
- ApiImplicitParam
- 메소드 단위의 오퍼레이션 파라미터 설명
springfox-boot-starter
- 기존에는 springfox swagger와 UI 두개의 dependency를 모두 가져야 했는데 최근 springfox boot starter로 한번에 사용할 수 있다.
1
2
3
4
5
6
7
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'
implementation group: 'io.springfox', name: 'springfox-boot-starter', version: '3.0.0'
}
- 해당 dependency를 작성하면 모든 Controller은 swagger로 공개된다.
- localhost:8080/swagger-ui/ 로 접속하면 아래의 사진처럼 작성한 controller들을 볼 수 있고 바로 실행도 시켜볼 수 있다.
Swagger설정 하기
controller tag설정
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
package com.example.swagger.controller;
import io.swagger.annotations.Api;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RestController;
@Api(tags = {"API 정보를 제공하는 Controller"})
@RestController
@RequestMapping("/api")
public class ApiController {
@GetMapping("/hello")
public String hello(){
return "hello";
}
}
- 간단하게 Api Annotation에 tag를 작성해주면 swagger에서 해당 tag로 controller가 나타난다.
Param 설명
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
package com.example.swagger.controller;
import io.swagger.annotations.Api;
import io.swagger.annotations.ApiParam;
import org.springframework.web.bind.annotation.*;
@Api(tags = {"API 정보를 제공하는 Controller"})
@RestController
@RequestMapping("/api")
public class ApiController {
@GetMapping("/hello")
public String hello(){
return "hello";
}
@GetMapping("/plus/{x}")
public int plus(
@ApiParam(value = "x값")
@PathVariable int x,
@ApiParam(value = "y값")
@RequestParam int y){
return x + y;
}
}
- 객체에 대한 설정도 추가할 수 있다.
- RequestParam, PathVarialbe에 ApiParam Annotation을 사용해 설명을 추가할 수 있다.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
package com.example.swagger.dto;
import io.swagger.annotations.ApiModelProperty;
import lombok.AllArgsConstructor;
import lombok.Data;
import lombok.NoArgsConstructor;
@Data
@NoArgsConstructor
@AllArgsConstructor
public class UserRes {
@ApiModelProperty(value = "사용자의 이름", example = "kms", required = true)
private String name;
@ApiModelProperty(value = "사용자의 나이", example = "28", required = true)
private int age;
}
- UserRes, UserReq를 만든 뒤 ApiModelProperty를 사용해 추가 설명을 사용할 수 있다.
1
2
3
4
@GetMapping("/user")
public UserRes user(UserReq userReq){
return new UserRes(userReq.getName(), userReq.getAge());
}
Error 응답 설정하기
1
2
3
4
5
@ApiResponse(code = 502, message = "사용자의 나이가 10살 이하일때")
@GetMapping("/user")
public UserRes user(UserReq userReq){
return new UserRes(userReq.getName(), userReq.getAge());
}
- Status code기준으로 설명을 추가할 수 있다.
