[Flask] REST API, swagger 적용

0. 들어가기

-. Flask-RESTX 적용 및 swagger 사용

1. RESTX 설치 및 기본시작

-. 기존에 있던 Flask-RESTPlus의 업데이트가 멈추고 이를 포크한 것이 RESTX

Welcome to Flask-RESTX’s documentation!

Flask-RESTX is an extension for Flask that adds support for quickly building REST APIs. Flask-RESTX encourages best practices with minimal setup. If you are familiar with Flask, Flask-RESTX should be easy to pick up. It provides a coherent collection of decorators and tools to describe your API and expose its documentation properly (using Swagger).

Flask-RESTX is a community driven fork of Flask-RESTPlus

1) 설치

-. pip로 간단하게 설치

 pip install flask-restx

-. 적용도 간단하게

import flask
from flask_restx import Api


def create_app():
    app = flask.Flask(__name__)
    api = Api()
    api.init_app(app)

	return app


app = create_app()

2) document ui

-. 단말 루트 ('/')에 들어가면 아래와 같이 swagger 초기 페이지가 보임.

3) api 단말 추가

-. 단말 '/hello' 추가

        @api.route('/hello')
        class HelloWorld(Resource):
            def get(self):
                return {'hello': 'world'}

-. 동시에 json 형태로 정리된 버전도 볼 수 있다.

{
   "swagger":"2.0",
   "basePath":"/",
   "paths":{
      "/hello":{
         "get":{
            "responses":{
               "200":{
                  "description":"Success"
               }
            },
            "operationId":"get_hello_world",
            "tags":[
               "default"
            ]
         }
      }
   },
   "info":{
      "title":"API",
      "version":"1.0"
   },
   "produces":[
      "application/json"
   ],
   "consumes":[
      "application/json"
   ],
   "tags":[
      {
         "name":"default",
         "description":"Default namespace"
      }
   ],
   "responses":{
      "ParseError":{
         "description":"When a mask can't be parsed"
      },
      "MaskError":{
         "description":"When any error occurs on mask"
      }
   }
}

4) api 정보 등록

-. api 이름과 버전, 간단한 설명 추가

    app = flask.Flask(__name__)
    api = Api(version='0.1', title='Dobby API', description='toy project API server')
    api.init_app(app)

 

2. Namespace

-. flask는 blueprint를 이용한 routing을 할 수 있다. flask-restx를 사용할 땐, blueprint 대신 namespace를 사용하면 된다.

#Flask
bp = Blueprint('home', __name__, url_prefix="/api/")

@bp.route('/check/', methods=['GET'])
def main():

#Flask-RESTX
ns = Namespace('api/v2/home')

@ns.route('/check/')  # /api/v2/home/check/
class Check(Resource):
    @staticmethod
    def get():

-. 위와 같이 코드를 수정하고 다시 swagger를 확인하면 문서에 라우팅 된 단말이 나타난다.

-. 하나의 namespace에 여러 endpoints가 있을 경우 아래와 같이 문서가 작성됨.