[파이썬] Flask의 API 개발과 Swagger 문서화

01 Sep 2023

python

Flask는 파이썬으로 구현된 마이크로 웹 프레임워크로, 간단하고 가벼운 웹 어플리케이션 개발에 적합한 도구입니다. Flask를 사용하여 RESTful API를 개발하고 관리하는 것은 매우 간편하며, Swagger를 사용하여 API 문서를 자동화할 수 있습니다. 이 글에서는 Flask에서 API를 개발하고 Swagger로 문서화하는 방법에 대해 알아보겠습니다.

Flask를 사용하여 API 개발하기

Flask를 사용하여 API를 개발하는 것은 매우 간단합니다. 먼저 Flask를 설치하고, 필요한 패키지들을 import하여 API 엔드포인트를 만들 수 있습니다. 아래는 간단한 예제 코드입니다.

from flask import Flask, jsonify, request

app = Flask(__name__)

@app.route('/api/resource', methods=['GET'])
def get_resource():
    resource = {'name': 'example', 'data': 'example data'}
    return jsonify(resource)

@app.route('/api/resource', methods=['POST'])
def create_resource():
    resource = request.json
    # 로직을 추가하여 리소스를 생성하는 코드
    return jsonify(resource), 201

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

위의 코드는 /api/resource 엔드포인트에 대한 GET과 POST 메소드를 정의한 예제입니다. GET 메소드는 예시 리소스를 반환하고, POST 메소드는 요청으로 받은 데이터로 새로운 리소스를 생성합니다.

Swagger로 API 문서화하기

API를 문서화하는 것은 중요한 작업입니다. Swagger는 개발자가 작성한 API 스펙을 기반으로 자동으로 문서화를 생성해주는 도구입니다. Flask-RESTPlus는 Flask 확장 모듈로, Swagger를 사용하여 API 문서를 자동화하는 기능을 제공합니다.

먼저 Flask-RESTPlus를 설치합니다.

$ pip install flask-restplus

다음은 Swagger를 사용하여 API 문서화하는 예제 코드입니다.

from flask import Flask
from flask_restplus import Api, Resource

app = Flask(__name__)
api = Api(app)

@api.route('/api/resource')
class Resource(Resource):
    def get(self):
        return {'name': 'example', 'data': 'example data'}

    def post(self):
        return {'message': 'Resource created successfully'}, 201

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

위의 코드에서 @api.route('/api/resource') 데코레이터를 사용하여 /api/resource 엔드포인트에 대한 Swagger 정의를 추가합니다. Swagger는 이 정의를 읽어와 API 문서를 자동으로 생성합니다. Flask 애플리케이션을 실행한 후 /api/swagger.json 엔드포인트로 접속하면 Swagger 문서를 확인할 수 있습니다.

Swagger UI로 API 문서 확인하기

Swagger로 생성한 API 문서는 Swagger UI를 사용하여 확인할 수 있습니다. Swagger UI는 API 문서를 시각적으로 보여주고, 사용법을 테스트할 수 있는 툴입니다. Flask-RESTPlus는 Swagger UI를 포함하고 있어서 손쉽게 사용할 수 있습니다.

Flask 애플리케이션에서 Swagger UI를 사용하려면 다음과 같이 코드에 추가하면 됩니다.

from flask import Flask
from flask_restplus import Api, Resource

app = Flask(__name__)
api = Api(app, doc='/api/swagger-ui')

# 라우트 및 API 정의 코드 생략

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

위의 코드에서 doc 옵션을 사용하여 Swagger UI를 /api/swagger-ui 엔드포인트로 배치합니다. Flask 애플리케이션을 실행한 후 해당 엔드포인트로 접속하면 Swagger UI를 사용할 수 있습니다.

마무리

위에서 소개한 방법을 사용하면 Flask를 사용하여 간편하게 API를 개발하고, Swagger를 사용하여 API 문서를 자동화할 수 있습니다. 이를 통해 개발자는 API를 빠르게 개발하고 문서화하는 데 집중할 수 있으며, 사용자는 Swagger UI를 통해 쉽게 API를 이해하고 테스트할 수 있습니다. Flask와 Swagger를 함께 사용하여 효율적인 API 개발을 진행해보세요!