Swagger란?
OAS(=Open Api Specification)이라고도 불린다.
개발자가 REST API 서비스를 보다 쉽게 설계, 빌드, 문서화할 수 있도록 하는 프로젝트이다.
Spring Boot에서 간단하게 springfox-boot-starter를 gradle dependencies에 추가함으로 사용할 수 있다.
단, 운영환경과 같이 외부에 노출되면 안되는 곳에서는 사용할때는 주의해야한다.
유사한 REST API 문서화 / 개발 프로젝트로는 GraphQL, RAML 등이 있다.
각 프로젝트의 차이점들은 해당 링크를 확인하면 된다.
SpringBoot에서 Swawgger 실행방법
(1) Maven Repository접속
링크 : https://mvnrepository.com/artifact/io.springfox/springfox-boot-starter/3.0.0
위 사이트로 들어가서 본인의 빌드 도구에 맞게 경로를 복사해주자.
또한 필요시 본인에게 맞는 Spring Boot Starter 버젼을 설치해주자. 참고로 위 링크는 3.0.0 버젼이다.
(2) Dependency 추가
gradle을 사용한다면 아래와같이 gardle의 depndencies에 방금 복사해둔 경로를 추가해준다.
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'
// 아래 코드가 swagger dependency
implementation group: 'io.springfox', name: 'springfox-boot-starter', version: '3.0.0'
}
그런다음 gradle을 재빌드 해준다.
(3) 간단한 예제 테스트
다음과 같이 간단한 예제를 작성한뒤 프로젝트를 구동한다.
그리고 다음의 경로로 들어가준다.
// 만약 설정한 포트가 8080이 아니라면 본인이 작성한 포트로 바꿔써준다.
http://localhost:8080/swagger-ui/
(4) 결과 확인
해당 경로로 들어가면 위와같이 자신이 작성한 API가 문서화 되어있는것을 확인해줄 수 있다.
이전에 Postman으로 API를 구동해줬을때는 일일이 경로를 작성해주고, 메소드를 설정해주는 번거로움이 있었지만
Swagger를 이용하면 번거로움없이 프로젝트 내부에 생성된 모든 API를 확인하고 그에따른 실행결과도 확인할 수 있다.
Swagger 추가 설정
(1) Api tag 붙이기
@Api(tags={"API 정보를 제공하는 Controller"})
(2) Api Param = 매개변수 설명하기
@GetMapping("/plus/{x}")
public int plus(
@ApiParam(value = "x값", defaultValue = "20")
@PathVariable int x,
@ApiParam(value = "y값", defaultValue = "10")
@RequestParam int y){
return x+y;
}
ApiParam을 쓰면 매개변수에 대한 설명과 기본값을 설정할 수 있지만, 매번 이렇게 작성할 경우 ApiController 내부가 길고 복잡하게 느껴질 수 있다. 보다 깔끔하게 사용하는 방법은 다음과 같다.
(3) ApiModelProperty
[UserRes.java, UserReq.java]
package com.example.swagger.dto;
import io.swagger.annotations.ApiModelProperty;
import lombok.AllArgsConstructor;
import lombok.Data;
import lombok.NoArgsConstructor;
@NoArgsConstructor
@AllArgsConstructor
@Data
public class UserRes { // 클래스명만 각기 다르게 사용하기
@ApiModelProperty(value = "사용자 이름", example ="Kim", required = true)
private String name;
@ApiModelProperty(value = "사용자 나이", example = "20",required = true)
private int age;
}
[ApiController내부]
@GetMapping("/user")
public UserRes user(UserReq userReq){
return new UserRes(userReq.getName(), userReq.getAge());
}
(4) ApiOperation = Api 설명 붙이기
@ApiOperation(value = "사용자의 이름과 나이를 리턴하는 메소드")
@GetMapping("/user")
public UserRes user(UserReq userReq){
return new UserRes(userReq.getName(), userReq.getAge());
}
(5) ApiResponse = 특정 Http Status Code 정의
@ApiResponse(code = 502, message = "사용자의 나이가 10살 이하일때")
@ApiOperation(value = "사용자의 이름과 나이를 리턴하는 메소드")
@GetMapping("/user")
public UserRes user(UserReq userReq){
return new UserRes(userReq.getName(), userReq.getAge());
}
이 외에도 다양한 Swagger Annotation이 있으니 필요할 때 찾아가며 활용하자.
'👩🏻💻 Programming > SpringBoot' 카테고리의 다른 글
JPA (0) | 2021.08.29 |
---|---|
RestTemplate과 WebClient (0) | 2021.08.22 |
스프링과 JUnit (0) | 2021.08.19 |
RestTemplate (0) | 2021.08.16 |
Spring과 비동기 처리 (0) | 2021.08.16 |