스웨거란? (Swagger, OpenAPI)

API 관련 업무를 하게 되면, 스웨거를 자주 접하게 된다. 

 

스웨거란 Open Api Specification(OAS)를 위한 프레임워크다. OpenAPI에서 빼놓을 수 없는 기능이 바로 swagger다. API 에디터 혹은 코드젠 혹은 API 매뉴얼 자동생성 및 테스트 사이트 생성으로 유명한 Swagger!

 

스웨거 설명 전에 먼저 OAS가 무엇인지 한번 살펴보자.

간단하게 말하면 아래와 같다.

• OpenAPI = Specification
• Swagger = Tools for implementing the specification

 

OAS(OpenAPI Specification)는 RESTful 웹서비스를 약속된 규칙에 따라 약속된 규칙에 맞게 API 스펙을 json과 yaml 형식으로 표현한다.  이를 통해, 직접 소스코드를 보거나 추가 문서 필요없이 서비스를 이해할 수 있다.

The OpenAPI Specification (OAS) defines a standard, language-agnostic interface to RESTful APIs which allows both humans and computers to discover and understand the capabilities of the service without access to source code, documentation, or through network traffic inspection. 

 

다시 돌아와서 스웨거는 API들이 가지고 있는 specification(스펙/spec/명세)를 관리할 수 있는 프로젝트다. 협업을 진행하거나 이미 만들어져 있는 프로젝트에 대해 유지보수를 진행하게 되면, 구축되어 있는 API 서버가 어떤 스펙을 가지고 있는지 파악해야 한다. 이러한 스펙을 정리하기 위해 API 문서화 작업을 하게 되고, 이 과정을 직접 손으로 하게 되면 API가 수정될 때마다 문서도 수정해주어야 하는 불편함이 생긴다. 이러한 불편함을  줄여주는 도구가 바로 Swagger Project다. 

 

Swagger는 OpenAPI 스펙을 맞춘 api-docs를 이용하여 html 페이지로 문서화해주는 프레임워크로, RESTful API의 설계 및 문서화에 매우 도움을 준다. 

 

Swagger의 기능

 

1. API 디자인

Swagger-editor를 통해 api를 문서화하고 빠르게 명세할 수 있다.

2. API Development

Swagger-codegen을 통해 작성된 문서를 통해 SDK를 생성하여 빌드 프로세스를 간소화할 수 있다. 

3. API Documnetation

Swagger-UI를 통해 작성된 API를 시각화시켜준다.

4. API Testing

Swagger-Insepctor를 통해 API를 시각화하고 빠른 테스팅을 진행할 수 있다.

5. Standardize

Swagger-hub를 통해 개인, 팀원들이 API 정보를 공유하는 Hub다.

 

 

Swagger 실습

 

flask로 간단한 API서버를 실행하고 swagger에서 접근을 시도하면, 해당 서버에 대한 API spec을 자동으로 생성해준다. 이때 REST API 형태로 프로그래밍만 해주면 간단한 문서와 예제 소스 코드가 생성되고, 간단히 실행도 할 수 있다. 일단 이렇게 만들어주면, 매뉴얼대로 했느데 안된다느니, 예제 소스 코드에 오타가 있다느니와 같은 문제는 발생하지 않는다. 

# -*- coding:utf-8 -*-
# Kei Choi (whchoi@nurilab.com)

# REST API로 구현한 계산기 예제

import werkzeug
werkzeug.cached_property = werkzeug.utils.cached_property

from flask import Flask
from flask_restplus import Resource, Api, reqparse


# -----------------------------------------------------
# api
# -----------------------------------------------------
app = Flask(__name__)
api = Api(app, version='1.0', title='Calc API',
          description='계산기 REST API 문서',)

ns = api.namespace('calc', description='계산기 API 목록')
app.config.SWAGGER_UI_DOC_EXPANSION = 'list'  # None, list, full


# -----------------------------------------------------
# 덧셈을 위한 API 정의
# -----------------------------------------------------
sum_parser = ns.parser()
sum_parser.add_argument('value1', required=True, help='연산자1')
sum_parser.add_argument('value2', required=True, help='연산자2')


@ns.route('/sum')
@ns.expect(sum_parser)
class FileReport(Resource):
    def get(self):
        """
                Calculate addition
        """
        args = sum_parser.parse_args()

        try:
            val1 = args['value1']
            val2 = args['value2']
        except KeyError:
            return {'result': 'ERROR_PARAMETER'}, 500

	result = {'result': 'ERROR_SUCCESS', 'value': int(val1) + int(val2)}
        return result, 200


if __name__ == '__main__':
    app.run(host='0.0.0.0', port=5000)  # , debug=True)

 

 

2. swagger editor를 사용해서 문서를 만든다.

 

openapi3.0 형식을 지킨 문서를 넣게 되면, 오른쪽에 API 문서가 작성된다.

https://editor.swagger.io/

 

 

3) swagger codgen을 활용해서 openapi 스펙 문서에 대한 client and server stub을 만들 수 있다.