flasgger の Marshmallow schema でクエリーストリングを扱う方法

• 概要
• 環境
• ライブラリインストール
• ソース
  • 説明
• 動作確認
• 最後に
• 参考サイト

概要

flasgger の Marshmallow schema でクエリストリングを扱う方法を紹介します
基本は swagger で扱う方法と同じです

環境

• macOS X 10.14
• Python 3.7
• flasgger 0.9.0

ライブラリインストール

• vim Pipfile

[[source]]
url = "https://pypi.org/simple"
verify_ssl = true
name = "pypi"

[packages]
flasgger = "*"
marshmallow = "*"
apispec = "==0.38.0"

[dev-packages]

[requires]
python_version = "3.6"

• pipenv install

ソース

• vim query_string.py

# coding: utf-8
from flask import Flask, jsonify, request
from flasgger import Schema, Swagger, SwaggerView, fields


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


class ConvertView(SwaggerView):
    summary = 'Show your name'
    description = 'Query string converts to json string'
    parameters = [
        {
            'name': 'name',
            'in': 'query',
            'description': 'Your name',
            'type': 'string'
        }
    ]
    responses = {
        200: {
            'description': 'Success jsonify',
            'schema': NameSchema
        }
    }

    def get(self):
        name = request.args['name']
        d = self.external_api(name)
        return jsonify(NameSchema().dump(d).data)

    def external_api(self, name):
        return {'name': name}


app = Flask(__name__)
app.add_url_rule(
    '/convert/',
    view_func=ConvertView.as_view('convert'),
    methods=['GET']
)
Swagger(app)


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

説明

parameters で in: query とすることでクエリーストリングとして扱うことができます
取得する場合は request.args['name'] で取得できます
もしくは request.args.get('name') とすることで指定のキーがない場合には None を設定することができます
さらに request.args は ImmutableMultiDict というクラスのオブジェクトになっており、get 時に型を指定したりデフォルト値を設定したりすることもできます

動作確認

• pipenv run python3 query_string.py

アプリを起動したら curl で確認します

• curl localhost:5000/convert/?name=hoge

クエリーストリングに指定した文字列が返ってくれば OK です

{
  "name": "hoge"
}

localhost:5000/apidocs/ にアクセスすると Swagger UI が確認できます
クエリーストリングの場合パラメータは以下のように表示されます

最後に

flasgger の Marshmallow schema でクエリーストリングを使ってみました
required や type チェックなどは自動で行ってくれないので validation なりを使う必要がありそうです

参考サイト

• https://swagger.io/docs/specification/describing-parameters/#query-parameters