Swagger

 Swagger를 사용하여, 기존에 Spring boot 프로젝트 API를 자동화한 적이 있다. 백엔드에서 만든 API 문서가 없더라도 내가 만든 코드에다가 Swagger 설정을 입혀서 자동화하도록 만들어 프런트에 제공했었다. Swagger를 이용했던 경험을 떠올려 구체적으로 어떤 기능과 역할이 가능한지 알아본다.

 

Open API란?

Open API 명세는 REST API를 위한 API 설명 형식으로 YAML 혹은 JSON으로 작성된다. 인간과 기계에 친화적이며 구체적인 공식 명세를 다음 링크에서 확인할 수 있다. OpenAPI 3.0 Specification

 

다음 API를 기술 할 수 있다.

 

- 사용 가능한 엔드포인트(/users) 및 각 엔드포인트의 작업(GET /users, POST /users) 
- 각 동작에 대한 동작 파라미터 입력 및 출력
- 인증 메서드
- 연락처 정보, 라이선스, 이용 약관 및 기타 정보

 

Open API 누구나 사용이 가능하며, 보통 서비스형태로 제공되어 각 제공처의 승인키를 발급받아야만 데이터를 사용하는 경우가 많다.

Swagger란 무엇인가?

Swagger는 REST API를 설계, 빌드, 문서화하도록 돕는 OpenAPI 명세로 만들어진 오픈소스 도구의 모음이다.

• Swagger Editor - 브라우저 기반 에디터로 Open API 명세를 작성한다.
• Swager UI - OpenAPI 명세를 대화형 API 문서로 렌더링한다.
• Swagger Codegen - OpenAPI 명세를 기반으로 서버 코드와 클라이언트 라이브러리를 만든다.

* Swagger Editor와 Swagger UI

Swagger Editor & Swagger UI

왼쪽이 Editor, 오른쪽이 UI이다. 다음의 2가지 방식으로 실제 프로젝트를 진행할 수 있다.

 

bottom-up(상향식)

코드가 짜여진 상태에서 명세를 만든다. Swagger definition을 직접 작성하거나 node.js 혹은 Swagger 지원하고있는 다른 프레임워크로 자동 생성한다.

top down(하향식)

명세를 먼저 작성하고 코드를 짠다. Swagger Editor을 이용하여 Swagger definition을 작성한다. Swagger Codegen을 이용하여 실제 서버 구현한다.

 

*Swagger Codegen

아래의 예시는 한 사이트의 튜토리얼을 가져온 것으로 Swagger Codegen의 실행흐름을 확인한다.

 

가장 먼저, 명세에 맞는 yaml파일을 작성한다. info, tag, paths 등에 대한 내용을 담는다.

swagger: '2.0' #version of Swagger
info: # High Level information of API
  description: Sample Swagger Demo #Give the description of API 
  version: 1.0.0 #API version
  title: Swagger Employee Demo # API title
  license: #Swagger license info
    name: Apache 2.0
    url: 'http://www.apache.org/licenses/LICENSE-2.0.html'
host: localhost # Host Name
basePath: /v1 #Basepath when there are multiple versions of API running
tags: # Tag information for each API operation. Multiple tags for multiple API operation
  - name: employee #Tag name
    description: Everything about your Employee #Tag description of API operation
schemes:
  - http #security schemes
paths:
  '/findEmployeeDetails/{employeeId}': #Request Mapping path of REST API
    get: #Request method type, GET,POST etc.
      tags: # Refer to created tag above
        - employee
      summary: Find employee by ID #Summary 
      description: Returns a single Employee #Description of API operation
      operationId: getEmployeeDetails #Method name
      produces:
        - application/json #Response content type
      parameters:
        - name: employeeId #Input parameter
          in: path #path variable
          description: ID of Employee to return #description of parameter
          required: true #Is mandatory
          type: integer #data type
          format: int64 #data type format, signed 64 bits
      responses: # API response
        '200': #Successful status code
          description: successful operation #Successful status description
          schema:
            $ref: '#/definitions/Employee' #Response object details
        '400': #Unsuccessful response code
          description: Invalid Employee ID supplied #Unsuccessful response description
        '404': #Unsuccessful response code
          description: Employee not found #Unsuccessful response description
definitions: # Object definition
  Employee: #Employee Object
    type: object
    properties: #Object properties
      id: #Id attribute
        type: integer
        format: int64
      firstName: #Firstname attribute
        type: string
        description: Employee First Name #data type description
      lastName: #Lastname attribute
        type: string #Data type
        description: Employee Last Name #Data type description
    xml:
      name: employee #xml root element when returning xml

 

작성한 swagger.yaml 문서를 swagger codegen으로 실행하면, API명세에 맞는 코드를 자동생성 할 수 있다. 

코드를 만들기 위해 codegen을 실행

아래 클래스는 생성된 파일 중 하나인 FindEmployeeDetailsApi 인터페이스이다.

 

* FindEmployeeDetailsApi.java

@javax.annotation.Generated(value = "io.swagger.codegen.languages.SpringCodegen", date = "2018-03-14T07:52:19.544+05:30")
 
@Api(value = "findEmployeeDetails", description = "the findEmployeeDetails API")
public interface FindEmployeeDetailsApi {
 
    @ApiOperation(value = "Find employee by ID", nickname = "getEmployeeDetails", notes = "Returns a single Employee", response = Employee.class, tags={ "employee", })
    @ApiResponses(value = { 
        @ApiResponse(code = 200, message = "successful operation", response = Employee.class),
        @ApiResponse(code = 400, message = "Invalid Employee ID supplied"),
        @ApiResponse(code = 404, message = "Employee not found") })
    @RequestMapping(value = "/findEmployeeDetails/{employeeId}",
        produces = { "application/json" }, 
        method = RequestMethod.GET)
    ResponseEntity<Employee> getEmployeeDetails(@ApiParam(value = "ID of Employee to return",required=true) @PathVariable("employeeId") Long employeeId);
 
}

명세에 작성한대로 다양한 @Api, @ApiOperation, @ApiResponse 등이 붙은 코드들을 확인할 수 있다.