Flask - Swagger UI 연동

Flask 프로젝트에 Swagger-UI를 연동하는 방법을 최신 자로 공유해드리려 합니다.

 

 

프로젝트 생성

 

우선 Flask 프로젝트를 하나 생성해줍니다.

 

from flask import Flask

app = Flask(__name__)


@app.route('/')
def hello_world():
    return 'Hello World!'


if __name__ == '__main__':
    app.run()

 

flask_restx 설치

 

후에 cmd창을 이용하여, 프로젝트에 flask_restplus가 아닌 flask_restx를 설치해 줍니다.

 

이 곳이 현재 Swagger UI 설치 중 가장 걸리는 부분 중 하나입니다.

그동안은 flask_restplus를 이용하여 Swagger UI를 이용하였지만, flask_restplus는 2020년을 마지막으로 서비스 종료되었습니다. 

그로 인하여 flask_restplus의 백업 모듈이라고 할 수 있는 flask_restx를 이용하여 Swagger를 사용해야 합니다.

 

pip install flask_restx

 

경로 설정

 

추후, 주요 기능을 import 해준 뒤 문서가 생성될 경로를 설정해 줍니다.

 

 

from flask import Flask
// 추가 부분
from flask_restx import Api, Resource, reqparse

app = Flask(__name__)

// 추가 부분
api = Api(app, version='1.0', title='API 문서', description='Swagger 문서', doc="/api-docs")


@app.route('/')
def hello_world():
    return 'Hello World!'


if __name__ == '__main__':
    app.run()

 

namespace 생성

 

api를 분류해줄 namespace를 생성해 줍니다.

 

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

app = Flask(__name__)

api = Api(app, version='1.0', title='API 문서', description='Swagger 문서', doc="/api-docs")

//추가 부분
test_api = api.namespace('test', description='조회 API')

@app.route('/')
def hello_world():
    return 'Hello World!'


if __name__ == '__main__':
    app.run()

 

Swagger UI에 API 등록

 

api를 Class로 변경해주고, namespace.route로 변경하는 등 아래와 같은 설정으로 바꿔줍니다.

 

주의 - 함수명이 get, post, put, del 등 RESTful API의 Method가 아니면 Swagger UI에 나타나지 않습니다.

 

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

app = Flask(__name__)

api = Api(app, version='1.0', title='API 문서', description='Swagger 문서', doc="/api-docs")

test_api = api.namespace('test', description='조회 API')


//변경 부분
@test_api.route('/')
class Test(Resource):
    def get(self):
    	return 'Hello World!'


if __name__ == '__main__':
    app.run()

 

Swagger UI 확인

위 설정한 경로를 들어가서 (default - http://localhost:5000/api-docs) 생성된 Swagger UI를 확인해 줍니다.