2018年7月22日日曜日

flasgger Marshmallow Schemas テクニック集

概要
環境
文字列のデフォルト値を設定する方法
文字列を enum として定義する方法
その他 fields に関するテクニック
メタ情報を設定する方法
スキーマクラスに直接 array タイプを定義したい
SwaggerView を使って API のパラメータとレスポンスを定義する
リクエストボディを取得する方法
スキーマを定義したのに definitions に出てこない

概要

flasgger の Marshmallow Schemas のテクニックを紹介します

環境

macOS X 10.13.6
Python 3.6.5
flasgger 0.9.0

文字列のデフォルト値を設定する方法

hoge = fields.Str(missing='TCP')

文字列を enum として定義する方法

hoge = fields.Str(enum=['A', 'B', 'C'])

その他 fields に関するテクニック

最小値

hoge = fields.Int(min=1)

Boolean

hoge = fields.Bool()

readOnly

hoge = fields.Str(dump_only=True)

メタ情報を設定する方法

タイトルなどのトップレベルでのメタ情報を定義する方法です

app = Flask(__name__)
meta_info = {
    'info': {
        'description': 'description',
        'title': 'title',
        'contact': {
            'name': 'https://hawksnowlog.blogspot.com'
        },
        'license': {
            'name': 'hawksnowlog'
        },
        'version': '1.0.0',
        'uiversion': 3,
        'termsOfService': '/there_is_no_tos'
    },
    'tags': [
        {
            'name': 'tag1',
            'description': 'tag1 description'
        },
    ],
    'schemes': ['https'],
    'basePath': '/v1/api',
    'host': 'localhost'
}
Swagger(app, template=meta_info)

スキーマクラスに直接 array タイプを定義したい

P.S 20180730 以下のように SwaggerView 側で array を定義することで可能だということがわかりました

class MyView(SwaggerView):
    parameters = [
        {
            'in': 'body',
            'name': 'HogeSpec parameter',
            'description': 'Test array parameter',
            'required': True,
            'schema': {
                'type': 'array',
                'items': {
                    '$ref': '#/definitions/HogeSchema'
                }
            }
        }
    ]

~~調査中、以下のようなことがやりたいができない~~

class TestSchema(Schema):
    fields.List(fields.Nested(HogeSchema))

で

[
  {
    'key': 'value'
  }
]

という構造を作成したいが以下のようにしないと動作しない

class TestSchema(Schema):
    fuga = fields.List(fields.Nested(HogeSchema))

{
  'fuga': [
    {
      'key': 'value'
    }
  ]
}

SwaggerView を使って API のパラメータとレスポンスを定義する

class MyView(SwaggerView):
    tags = ['tag1']
    summary = 'summary'
    description = 'description'
    operationId = 'operationId'
    consumes = ['application/json']
    produces = ['application/json']
    parameters = [
        {
            'in': 'path',
            'name': 'id',
            'required': True,
            'type': 'string',
        }
    ]
    responses = {
        200: {
            'description': 'OK',
            'schema': TestSchema
        }
    }

定義した View は add_url_rule で追加することで API として動作させます

app = Flask(__name__)
app.add_url_rule(
    '/my',
    view_func=MyView.as_view('my'),
    methods=['GET']
)

リクエストボディを取得する方法

from flask import request

request.json.get('Hoge')

スキーマを定義したのに definitions に出てこない

どうやら SwaggerView 側の schema で参照しないと JSON には登場しません
なので

'schema': {
  'type': 'array',
  'items': {
    '$ref': '#/definitions/HogeSchema'
  }
}

こんな感じでスキーマ参照しているとスキーマがないと言われてエラーとなります
そんな場合には definitions というパラメータで明示的に指定してあげることで JSON に登場させることができます

definitions = {
    'HogeSchema': HogeSchema
}

参考: https://github.com/rochacbruno/flasgger/issues/108

hawksnowlog