Swagger 설정 2

테스트를 진행할 예제: 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());
    }