SpringBoot와 Swagger

 

Swagger란?

 

OAS(=Open Api Specification)이라고도 불린다.

개발자가 REST API 서비스를 보다 쉽게 설계, 빌드, 문서화할 수 있도록 하는 프로젝트이다.

Spring Boot에서 간단하게 springfox-boot-starter를 gradle dependencies에 추가함으로 사용할 수 있다.

단, 운영환경과 같이 외부에 노출되면 안되는 곳에서는 사용할때는 주의해야한다.

 

유사한 REST API 문서화 / 개발 프로젝트로는 GraphQL, RAML 등이 있다.

각 프로젝트의 차이점들은 해당 링크를 확인하면 된다.

GraphQL과 Swagger(OAS), 그리고 RAML(RESTful API Modeling Language)

 

 

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이 있으니 필요할 때 찾아가며 활용하자.