Flask

Chapter 2-4 Flask-Smorest 활용하여 REST API 생성

Chansman 2025. 4. 18. 10:33

📌 Flask-Smorest 활용하여 REST API 생성

1. flask-smorest란?

flask-smorest는 Flask에서 REST API를 쉽게 작성할 수 있도록 도와주는 라이브러리입니다. 이 라이브러리는 Flask-RESTful보다 더 많은 기능을 제공하며, 특히 OpenAPI(Swagger) 문서 자동 생성 기능을 지원하는 것이 큰 특징입니다.

주요 특징

  • REST API 작성 용이성: API를 직관적으로 작성할 수 있도록 도와줍니다.
  • 자동 Swagger 문서화: API가 생성되면 Swagger UI로 API 문서를 자동으로 생성해 제공합니다.
  • Marshmallow 연동: 데이터 검증 및 직렬화를 위한 Marshmallow 라이브러리와 함께 사용됩니다.

2. Library 설치

Flask-Smorest를 설치하려면 pip를 사용합니다.

설치 명령어

> pip install flask-smorest

3. API 구축 (1) OpenAPI 설정

OpenAPI 설정을 통해 API의 제목, 버전, Swagger UI의 경로 등을 정의합니다. 아래 코드에서는 이를 app.py 파일에 설정하는 방법을 보여줍니다.

app.py - Flask 애플리케이션 설정

from flask import Flask
from flask_smorest import Api
from api import blp  # Blueprint

app = Flask(__name__)

# OpenAPI 관련 설정
app.config["API_TITLE"] = "My API"
app.config["API_VERSION"] = "v1"
app.config["OPENAPI_VERSION"] = "3.1.3"
app.config["OPENAPI_URL_PREFIX"] = "/"
app.config["OPENAPI_SWAGGER_UI_PATH"] = "/swagger-ui"
app.config["OPENAPI_SWAGGER_UI_URL"] = "https://cdn.jsdelivr.net/npm/swagger-ui-dist/"

api = Api(app)
api.register_blueprint(blp)  # Blueprint 등록

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

설명:

  • OPENAPI_VERSION: 사용하고자 하는 OpenAPI 버전을 설정합니다.
  • OPENAPI_URL_PREFIX: OpenAPI URL의 접두사(기본 값 /).
  • OPENAPI_SWAGGER_UI_PATH: Swagger UI 경로를 설정합니다.
  • OPENAPI_SWAGGER_UI_URL: Swagger UI의 CDN URL을 설정하여, API 문서화 도구를 브라우저에서 쉽게 사용하도록 합니다.

4. API 구축 (2) Schemas 설정

Marshmallow 라이브러리를 활용하여 데이터 검증 및 직렬화/역직렬화를 위한 스키마를 설정합니다. 스키마는 데이터 구조를 정의하고 검증을 수행하는 데 사용됩니다.

schemas.py - Marshmallow 스키마 정의

from marshmallow import Schema, fields

class ItemSchema(Schema):
    id = fields.Int(dump_only=True)  # 서버에서 관리하는 ID 필드
    name = fields.Str(required=True)  # 필수로 요구되는 이름 필드
    description = fields.Str()  # 선택적인 설명 필드

Marshmallow란?

  • Marshmallow는 데이터 직렬화/역직렬화 및 유효성 검사를 위한 라이브러리입니다. Python 객체를 JSON으로 변환하거나, JSON 데이터를 Python 객체로 변환할 때 유용하게 사용됩니다.

설치 명령어:

bash
복사
> pip install marshmallow

5. API 구축 (3) Blueprint

Blueprint는 Flask 애플리케이션에서 기능별로 라우팅과 관련된 모든 것을 모듈화하여 관리할 수 있도록 도와주는 기능입니다. 이를 통해 API를 더 체계적으로 관리할 수 있습니다.

Blueprint 설정

from flask_smorest import Blueprint

blp = Blueprint("items", "items", url_prefix="/items", description="Operations on items")
  • url_prefix="/items": 이 Blueprint에서 정의된 모든 URL 경로는 /items로 시작합니다.
  • description="Operations on items": Blueprint에 대한 설명을 추가합니다.

Blueprint 예시 코드

@blp.route("/")
class ItemList(MethodView):
    @blp.response(200)
    def get(self):
        return items  # 모든 아이템 반환

    @blp.arguments(ItemSchema)
    @blp.response(201, description="Item added")
    def post(self, new_data):
        items.append(new_data)  # 새 아이템 추가
        return new_data

6. API 구축 (4) Abort 함수

abort 함수는 오류가 발생했을 때 특정 HTTP 상태 코드와 메시지를 반환하는데 사용됩니다. 오류가 발생하면, abort를 호출하여 에러 메시지와 함께 클라이언트에 응답을 보냅니다.

abort 사용법

from flask_smorest import abort

# 오류 상황에서 abort 호출
abort(404, message="Resource not found")

예시 코드

from flask import Flask
from flask_smorest import abort

app = Flask(__name__)

@app.route('/example')
def example():
    error_condition = True

    if error_condition:
        abort(500, description="An error occurred while processing the request.")
    
    return "Success!"

7. API 구축 (5) API 생성

이제 API를 구성하여 클라이언트와 통신할 수 있는 RESTful 서비스를 제공합니다.

api.py - API 구현

from flask.views import MethodView
from flask_smorest import Blueprint, abort
from schemas import ItemSchema

# 블루프린트 생성: 'items'라는 이름으로, URL 접두사는 '/items'
blp = Blueprint("items", "items", url_prefix="/items", description="Operations on items")

items = []  # 간단한 데이터 저장소 역할을 하는 리스트

@blp.route("/")
class ItemList(MethodView):
    @blp.response(200)
    def get(self):
        return items  # 모든 아이템 반환

    @blp.arguments(ItemSchema)
    @blp.response(201, description="Item added")
    def post(self, new_data):
        items.append(new_data)  # 새 아이템 추가
        return new_data

@blp.route("/<int:item_id>")
class Item(MethodView):
    @blp.response(200)
    def get(self, item_id):
        item = next((item for item in items if item["id"] == item_id), None)
        if item is None:
            abort(404, message="Item not found")
        return item

    @blp.arguments(ItemSchema)
    @blp.response(200, description="Item updated")
    def put(self, new_data, item_id):
        item = next((item for item in items if item["id"] == item_id), None)
        if item is None:
            abort(404, message="Item not found")
        item.update(new_data)
        return item

    @blp.response(204, description="Item deleted")
    def delete(self, item_id):
        global items
        if not any(item for item in items if item["id"] == item_id):
            abort(404, message="Item not found")
        items = [item for item in items if item["id"] != item_id]
        return ''

8. Swagger UI

Swagger UI는 API 문서화 도구로, OpenAPI 사양을 사용하여 API를 시각적으로 표현하고 테스트할 수 있게 해줍니다. Swagger UI는 클라이언트가 API를 어떻게 호출할 수 있는지 쉽게 이해하도록 도와줍니다.

Swagger UI 접속 방법

  • Flask 애플리케이션 실행 후, 브라우저에서 **http://localhost:5000/swagger-ui**로 접속하여 API 문서를 확인할 수 있습니다.

9. flask-smorest의 장/단점

장점

  • OpenAPI 및 Swagger 문서화: 자동으로 API 문서를 생성하여 API의 사용 방법을 쉽게 파악할 수 있습니다.
  • Marshmallow와의 통합: 데이터 검증, 직렬화 및 역직렬화를 손쉽게 처리할 수 있습니다.
  • 모듈화: Blueprint를 통해 API를 모듈화하여 관리할 수 있습니다.

단점

  • 상대적인 러닝 커브: Flask-RESTful보다 사용법을 익히는 데 조금 더 시간이 걸릴 수 있습니다.
  • 설정의 복잡성: 일부 고급 기능을 구현하려면 추가 설정이 필요할 수 있습니다.

이로써 flask-smorest를 사용하여 RESTful API를 구현하는 방법과 관련된 기본 개념, 설정 및 실제 API 구현을 살펴보았습니다. Swagger UI를 통한 자동 문서화와 Marshmallow를 활용한 데이터 검증이 포함된 강력한 API 개발 도구입니다.