flasgger の Marshmallow Schemas を使ってみた

• 概要
• 環境
• インストール
• アプリ作成
• アプリ起動
• 動作確認
• 最後に
• 参考サイト

概要

flasgger には swagger ファイルをいろいろな形式で定義することができます
その中に Marshmallow Schemas というものがあります
Pythonのライブラリに marshmallow というものがありこれはオブジェクトのシリアライズを簡単に行うことができます
flasgger で marshmallow を使うでき、これを使うと Python でクラスを定義するように swagger を定義することができます
今回はサンプルを動かしてみました

環境

• macOS X 10.13.6
• Python 3.6.5
• flasgger 0.9.0
• apispec 0.38.0

インストール

• pipenv install flasgger marshmallow apispec=="0.38.0"

apispec というモジュールに依存しているのですが、これの最新版が 0.39.0 になっています
まだ flasgger 側が 0.39.0 に対応していないため一つ前のバージョンを明示的に指定します
Pull request はすでに出ているようでこれがマージされれば apispec の最新版が使えます

アプリ作成

Marshmallow Schemas を使ったサンプルアプリを作成します
swagger 定義をコードに記載するので既存の定義ファイルは使いません

• vim test_app.py

from flask import Flask, jsonify
from flasgger import Swagger, SwaggerView, Schema, fields


class Color(Schema):
    name = fields.Str()

class Palette(Schema):
    pallete_name = fields.Str()
    colors = fields.Nested(Color, many=True)

class PaletteView(SwaggerView):
    parameters = [
        {
            "name": "palette",
            "in": "path",
            "type": "string",
            "enum": ["all", "rgb", "cmyk"],
            "required": True,
            "default": "all"
        }
    ]
    responses = {
        200: {
            "description": "A list of colors (may be filtered by palette)",
            "schema": Palette
        }
    }

    def get(self, palette):
        """
        Colors API using schema
        This example is using marshmallow schemas
        """
        all_colors = {
            'cmyk': ['cian', 'magenta', 'yellow', 'black'],
            'rgb': ['red', 'green', 'blue']
        }
        if palette == 'all':
            result = all_colors
        else:
            result = {palette: all_colors.get(palette)}
        return jsonify(result)

app = Flask(__name__)
swagger = Swagger(app)

app.add_url_rule(
    '/colors/<palette>',
    view_func=PaletteView.as_view('colors'),
    methods=['GET']
)

app.run(debug=True)

definitions の役割は Schema クラスを継承した子クラスとして定義します
paramters と responses の部分は SwaggerView クラスを継承した子クラスとして定義します
ルーティングは app.add_url_rule で定義します

アプリ起動

• pipenv run python3 test_app.py

localhost:5000 で起動します

動作確認

• curl http://localhost:5000/colors/all/

で動作します
/apidocs/ で swagger UI が確認できます

最後に

参考サイト

• https://github.com/rochacbruno/flasgger/pull/205