step 1

테스트를 진행할 예제: http://localhost:8080/swagger-ui/

어노테이션 사용 예제

@Api: Swagger를 이용할 때 API Controller의 설명을 지정해 줄 수 있다.

// @Api: Swagger를 이용할 때 API Controller의 설명을 지정해 줄 수 있다.
@Api(tags = {"API 정보를 제공하는 Controller"})
@RestController
@RequestMapping("/api")
public class ApiController {

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

화면

Get 방식 파라미터 변수마다 설명을 달아주는 방법

@ApiParam: 파라미터 하나 하나 설명을 달아 줄 때 사용

@ApiImplicitParams: 메소드 단위에서 파라미터 설명을 달아 줄 때 사용

    // 파라미터 값을 받는 예제
    // 파라미터의 하나 하나설명을 달아주는 방법: @ApiParam
//    @GetMapping("/plus/{x}")
//    public int plus(
//                    @ApiParam(value = "X값")
//                    @PathVariable int x,
//                    @ApiParam(value = "Y값")
//                    @RequestParam int y){
//        return x + y;
//    }

    // 파라미터의 배열의 형태로 설명을 달아주는 방법: @ApiImplicitParams
    @GetMapping("/plus/{x}")
    @ApiImplicitParams(
            {
              @ApiImplicitParam(value = "x 값", name = "x", required = true, dataType = "int", paramType = "path"),
              @ApiImplicitParam(value = "y 값", name = "y", required = true, dataType = "int", paramType = "query")
            }
    )
    public int plus(@PathVariable int x, @RequestParam int y){
        return x + y;
    }

화면

DTO로 데이터를 전달 받을 경우 설명을 붙여주는 방법

controller 코드

@ApiOperation: 해당 메소드의 설명을 붙여줄 수 있다.

@ApiResponse: 각 응답 코드의 설명을 붙여줄 수 있다.

    // DTO를 사용할 경우 해당 요소마다 설명을 붙여주는 예제 DTO 내 변수에 설명을 붙여준다.
    // @ApiOperation: 해당 메소드의 설명을 붙여주는 방법
    @ApiOperation(value = "사용자의 이름과 나이를 리턴 하는 메소드")
    // @ApiResponse: 응답 코드의 따른 설명을 붙여주는 방법
    @ApiResponse(code = 502, message = "사용자의 나이가 10살 이하일때")
    @GetMapping("/user")
    public UserRes user(UserReq userReq){

        return new UserRes(userReq.getName(), userReq.getAge());
    }

DTO 코드

전달 될 때 DTO

@ApiModelProperty: 어노테이션을 이용해서 각 요소의 설명을 달아 줄 수 있다.

package com.example.swagger.dto;

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

@Data
@NoArgsConstructor
@AllArgsConstructor
public class UserReq {

    // Swagger의 설명을 붙여주는 방법: @ApiModelProperty
    @ApiModelProperty(value = "Req 사용자의 이름", example = "steve", required = true)
    private String name;

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

전달 받을 DTO

@ApiModelProperty: 어노테이션을 이용해서 각 요소의 설명, 기본값을 설정해서 어떠한 값이 나올지 예상할 수 있다.

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 = "Res: 사용자의 이름", example = "steve", required = true)
    private String name;

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

화면

Post방식의 예제

Get 방식과 같은 방법으로 설명을 달아 줄 수 있다.

    // post 방식 또한 같은방법으로 설명을 붙여줄 수 있다.
    @PostMapping("/user")
    public UserRes userPost(@RequestBody UserReq req){
        return new UserRes(req.getName(), req.getAge());
    }

프로젝트 생성후 dependency의 Springfox Boot Starter 추가

https://mvnrepository.com/artifact/io.springfox/springfox-boot-starter/3.0.0

테스트를 진행할 controller 생성

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("/api")
public class ApiController {

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

Swagger의 접속 (반드시 뒤에 "/" 를 붙여줘야 한다.) -> 해당 api의 결과를 확인할 수 있다.

http://localhost:8080/swagger-ui/

확인

Swagger란 개발한 REST API를 편리하게 문서화 해주고 이를 통해서 관리 및 제3의 사용자가 편리하게 API를 호출해보고 테스트 할 수 있는 프로젝트이다.

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

다만, 주의할 점은 운영환경과 같은 외부에 노출되면 안되는 곳에는 사용할 땐 주의 해야 한다.