[ 스프링부트 / Spring Boot ] Swagger 간단히 구현

작업 환경

IDE: intellij

JDK: 11

Spring: Spring Boot 2.5.1 + Gradle

 

1. 들어가기전

• Swagger
  REST 웹 서비스를 제공하려면 프론트엔드 개발자에게 전달해줄 API문서가 필수적이다.
  그런 문서를 작업해서 전달해주는건 수고로운 일이다.
  그래서 나타난게 Swagger이며, 이것은 문서뿐 아니라 빌드, 테스트 케이스, 등도 작성할 수 있다.

스웨거(Swagger)는 개발자가 REST 웹 서비스를 설계, 빌드, 문서화, 소비하는 일을 도와주는 대형 도구 생태계의 지원을 받는 오픈 소스 소프트웨어 프레임워크이다. 대부분의 사용자들은 스웨거 UI 도구를 통해 스웨거를 식별하며 스웨거 툴셋에는 자동화된 문서화, 코드 생성, 테스트 케이스 생성 지원이 포함된다.  / 위키 백과

 

Swagger github: https://github.com/swagger-api/swagger-core/wiki/Swagger-2.X---Getting-started

swagger-api/swagger-core

---

2. 구현하기

 

1. build.gradle 설정

build.gradle에 아래와 같이 설정했다. 

실질적으로 필요한 코드 implementation group: 'io.springfox', name: 'springfox-boot-starter', version: '3.0.0'

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'
}

표시된 부분이 Swagger 설정

2. Controller 등록

테스트할 RestController를 생성한다.

package com.example.swagger.controller;

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

@RestController
@RequestMapping("/test/api")
public class TestController {

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

 

3. 서버실행 후 Swagger UI 접속

서버를 실행 한 후 로컬서버에 기본포트(8080)인 경우 http://localhost:8080/swagger-ui/ 접속

 - Swagger 3.x인 경우 http://localhost:8080/swagger-ui/

 - Swagger 2.x인 경우 http://localhost:8080/swagger-ui.html

Swagger UI 페이지

---

3. 설정 및 옵션 지정하기

 

1. 컨트롤러 설정

• @Api: 해당 컨트롤러에 내용을 설정
• @ApiImpicitParams: 컨트롤러에 매핑될 파라미터들에 설정
• @ApiImpicitParam: 매핑될 파라미터 하나의 내용을 설정
• @ApiResponse: 응답 코드에 대한 설명
• @ApiOperation: 매핑 메소드에 대한 설명

package com.example.swagger.controller;

import com.example.swagger.dto.UserReq;
import com.example.swagger.dto.UserRes;
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 = "x", value = "x 값", required = true, dataType = "int", paramType = "path")
            , @ApiImplicitParam(name = "y", value = "y 값", required = true, dataType = "int", paramType = "query")
    })
    @GetMapping("/plus/{x}")
    public int plus(@PathVariable int x, @RequestParam int y){
        return x + y;
    }

    @ApiResponse(code = 502, message = "사용자의 나이가 10살 이하일 때")
    @ApiOperation(value = "사용자의 이름과 나이를 리턴하는 메소드")
    @GetMapping("/user")
    public UserRes user(UserReq userReq){
        return new UserRes(userReq.getName(), userReq.getAge());
    }

    @PostMapping("/user")
    public UserRes userPost(@RequestBody UserReq req){
        return new UserRes(req.getName(), req.getAge());
    }
}

 

2. Entity 설정

• @ApiModelProperty: 속성의 내용, 예문, 필수여부 등을 설정

package com.example.swagger.dto;

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

@Data
@NoArgsConstructor
@AllArgsConstructor
public class UserReq {

    @ApiModelProperty(value="사용자의 이름", example = "홍길동", required = true)
    private String name;

    @ApiModelProperty(value="사용자의 나이", example = "10", required = true)
    private int age;
}

 

<실행화면>

 

 

 

4. 그 외 설정

•  SwaggerConfig 파일을 만들어 그 외에 설정들을 등록할 수도 있다.
• 현재 작성된 코드는 Api문서에 관련된 정보를 수정한 것이다.

package com.example.swagger.config;

import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import springfox.documentation.builders.ApiInfoBuilder;
import springfox.documentation.builders.PathSelectors;
import springfox.documentation.builders.RequestHandlerSelectors;
import springfox.documentation.service.ApiInfo;
import springfox.documentation.service.Contact;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2;

@Configuration
@EnableSwagger2
public class SwaggerConfig {

    @Bean
    public Docket swagger() {
        return new Docket(DocumentationType.SWAGGER_2)
                .ignoredParameterTypes(java.sql.Date.class)
                .forCodeGeneration(true)
                .select()
                .apis(RequestHandlerSelectors.any())
                .paths(PathSelectors.any())
                .build()
                .apiInfo(apiInfo())
                .enable(true);
    }

    private ApiInfo apiInfo(){
        return new ApiInfoBuilder()
                .title("테스트 API 타이틀")
                .description("테스트 API 상세소개 및 사용법 등")
                .contact(new Contact("mile", "milenote.tistory.com", "skn@futurenuri.com"))
                .version("1.0")
                .build();
    }
}

<실행화면>

---

4. 마무리

Swagger를 통해 API 문서를 만드는 수고로움뿐만 아니라, 테스트 케이스를 만들 수 있는게 좋은 장점인 것 같다.

아직 자세한 기능들에 대해선 다 써보진 않았지만, 버전관리도 가능한 것 같다.

이 기능을 통해 다른 프로그램없이 테스트하는게 좋은 점 같다.

 

그리고 배포된 상태에선 사용하지 못하게 해야함으로, Profiles 설정을 꼭 걸어야할 것 같다.

 

 

 

- 작업한 소스: https://github.com/SimKyunam/fastcampus-swagger-practice

SimKyunam/fastcampus-swagger-practice