들어가기 전에

전 시간에는 Spring MVC와 Swagger를 사용하도록 프로젝트를 생성했습니다.

이번 시간엔 생성된 프로젝트에 Web API를 추가하고 Swagger를 이용해 테스트하겠습니다.

학습 목표

1. Spring MVC프로젝트에 Web API를 추가하고, Swagger를 이용하여 명세를 확인하고 테스트 할 수 있습니다.

핵심 개념

• Swagger를 이용한 Web API 자동 명세화 및 테스트

학습하기

이번 시간엔 지난 시간에 생성한 웹 프로젝트에 덧셈, 뺄셈을 하는 기능을 가진 Web API를 추가하고 

스웨거를 이용해 자동으로 생성된 명세를 확인하고 테스트하겠습니다.

1. CalculatorService 클래스 작성하기

덧셈, 뺄셈 기능을 가진 CalculatorService클래스를 작성합니다.

package org.edwith.webbe.calculator.service;

import org.springframework.stereotype.Service;

@Service
public class CalculatorService {
    public int plus(int value1, int value2){
        return value1 + value2;
    }

    public int minus(int value1, int value2){
        return value1 - value2;
    }
}

CalculatorService클래스는 컴포넌트 스캔을 통해 자동으로 Bean으로 등록됩니다.

2. Web API 클래스 작성하기

다음과 같은 기능을 가진 Web API를 작성해보도록 하겠습니다.

결과값을 표현하는 CalculatorResult클래스를 다음과 같이 작성합니다.

package org.edwith.webbe.calculator.dto;

public class CalculatorResult {
    // 아래의 상수값은 enum으로 변경 가능하다.
    public static final String PLUS_OPERATION = "+";
    public static final String MINUS_OPERATION = "-";

    private int value1;
    private int value2;
    private String operation;
    private int result;

    public int getValue1() {
        return value1;
    }

    public void setValue1(int value1) {
        this.value1 = value1;
    }

    public int getValue2() {
        return value2;
    }

    public void setValue2(int value2) {
        this.value2 = value2;
    }

    public String getOperation() {
        return operation;
    }

    public void setOperation(String operation) {
        this.operation = operation;
    }

    public int getResult() {
        return result;
    }

    public void setResult(int result) {
        this.result = result;
    }
}

컨트롤러 클래스를 작성합니다.

package org.edwith.webbe.calculator.controller.api;

import io.swagger.annotations.*;
import org.edwith.webbe.calculator.dto.CalculatorResult;
import org.edwith.webbe.calculator.service.CalculatorService;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.web.bind.annotation.*;

import java.util.List;

@RestController
@RequestMapping(path = "/api/calculator")
public class CalculatorApiController {
    @Autowired
    private CalculatorService calculatorService;

    @ApiOperation(value = "덧셈 구하기")
    @ApiResponses({  // Response Message에 대한 Swagger 설명
            @ApiResponse(code = 200, message = "OK"),
            @ApiResponse(code = 500, message = "Exception")
    })
    @GetMapping("/plus")
    public CalculatorResult plus(@RequestParam("value1")int value1, @RequestParam("value2") int value2){
        CalculatorResult calculatorResult = new CalculatorResult();
        calculatorResult.setValue1(value1);
        calculatorResult.setValue2(value2);
        calculatorResult.setOperation(CalculatorResult.PLUS_OPERATION);
        calculatorResult.setResult(calculatorService.plus(value1, value2));
        return calculatorResult;
    }

    @ApiOperation(value = "덧셈 구하기")
    @ApiResponses({  // Response Message에 대한 Swagger 설명
            @ApiResponse(code = 200, message = "OK"),
            @ApiResponse(code = 500, message = "Exception")
    })
    @GetMapping("/minus")
    public CalculatorResult minus(@RequestParam("value1")int value1, @RequestParam("value2") int value2){
        CalculatorResult calculatorResult = new CalculatorResult();
        calculatorResult.setValue1(value1);
        calculatorResult.setValue2(value2);
        calculatorResult.setOperation(CalculatorResult.MINUS_OPERATION);
        calculatorResult.setResult(calculatorService.minus(value1, value2));
        return calculatorResult;
    }
}

응답 결과를 JSON으로 하기 위해서 @RestController 어노테이션을 클래스 위에 붙여줍니다.

PATH가 공통적으로 "/api/calculator"로 하기 위해서 클래스 위에 @RequestMapping(path = "/api/calculator") 를

붙여주었습니다.

@ApiOperation과 @ApiResponse는 스웨거가 제공하는 어노테이션입니다.

@ApiOperation은 Web API의 간단한 설명을 적어줄 때 사용합니다.

아래는 ‘덧셈 구하기’라는 설명을 표현하고 있습니다.

@ApiOperation(value = "덧셈 구하기")

@ApiResponse는 응답 메시지에 대한 명세를 위해 사용합니다.

HTTP 응답 코드에 따라서 어떤 결과를 나타내는지 설명하고 있습니다. 

200 응답 코드일 경우에는 ‘OK’를, 500 응답 코드일 경우에는 ‘Exception’인 것을 표현합니다.

@ApiResponses({  // Response Message에 대한 Swagger 설명
            @ApiResponse(code = 200, message = "OK"),
            @ApiResponse(code = 500, message = "Exception")
    })

3. Web API 실행하기

Context Root경로를 /calculator로 지정하고 웹 어플리케이션을 실행합니다. 

웹 어플리케이션을 실행한 후 브라우저에서 다음과 같은 URL을 입력합니다.

http://localhost:8080/calculator/api/calculator/plus?value1=5&value2=10

4. 자동 생성된 스웨거 화면 확인하기

브라우저에서 http://localhost:8080/calculator/swagger-ui.html을입력하면 다음과 같은 화면이 보여집니다.

생각해보기

이번 시간엔 스웨거를 이용해 자동으로 생성된 Web API 명세를 확인하고, 테스트를 수행해 보았습니다.

@ApiOperation, @ApiResponse등의 어노테이션을 이용해 추가적인 설명을 붙였었는데요. 

Web API를 자동으로 생성하지 않는다면 어떤 문제가 있을지 생각해보시기바랍니다.

참고 자료