Python OpenAPIライブラリ bravado-core の発展的な使い方

Tweet

bravado-coreの発展的な使い方

この記事はPython Advent Calendar 2017 その2の17日目の記事です。

ソフトウェアエンジニアの和田です。以前の記事にて、OpenAPI（旧Swagger）を扱うことができるPythonライブラリbravado-coreのご紹介をさせていただきました。bravado-coreには、様々なWebアプリケーションフレームワークに柔軟に対応する仕組みが用意されており、これを利用することでOpenAPIドキュメントを用意するだけで、クライアントリクエストのバリデーションやUnmarshalingを行うことができます。弊社カブクの一部のサービスでは、この機能を利用し開発効率化を行っています。

本記事のソースコードは、Python3.6にて記述しています。ソースコードは、GitHubにて公開しています。

Flaskで使ってみる

Flaskで利用する例をご紹介いたします。FlaskではFlask-RESTfulを使用することでREST APIを簡潔に定義することが可能ですが、今回はbravado-coreの説明をするため、Flask-RESTfulを使用せずに実装します。また本筋に関係ないエラー処理などについては今回は省略して説明します。

実装するもの

実装するアプリケーションとしては、あらかじめ定義されている本（Bookクラス）の情報を操作するためのAPIを考えます。

bravado-coreを使わない場合

シンプルな実装例としては次のようになります。/books/<book_id>で指定されるbook_idを持つBookデータの取得、編集、削除を提供するAPIです。

from typing import Dict
import attr
from flask import Flask, request, jsonify


app = Flask(__name__)


@attr.s
class Book:
    title: str = attr.ib()
    published_year: int = attr.ib()


Books: Dict[int, Book] = {
    1: Book('The Internet Galaxy', 2003),
    2: Book('Prison Notebooks', 2010)
}


@app.route('/books/<int:book_id>', methods=['GET', 'PUT', 'DELETE'])
def book(book_id: int):
    target = Books.get(book_id)
    if not target:
        return jsonify(error=404, text="No book with book_id: {}".format(book_id)), 404

    if request.method == 'GET':
        resp = attr.asdict(target)
        resp.update({'id': book_id})
        return jsonify(resp)

    elif request.method == 'PUT':
        req = request.json
        if not req:
            return jsonify(error=400, text="Bad request"), 400

        if 'id' not in req or \
           'title' not in req or \
           'published_year' not in req:
            return jsonify(error=400, text="Bad request"), 400

        if not isinstance(req['title'], str):
            return jsonify(error=400, text="Bad request"), 400

        if not isinstance(req['published_year'], int):
            return jsonify(error=400, text="Bad request"), 400

        if book_id != req['id']:
            return jsonify(error=400, text="Bad request"), 400

        target.title = req['title']
        target.published_year = req['published_year']

        resp = attr.asdict(target)
        resp.update({'id': book_id})
        return jsonify(resp)

    elif request.method == 'DELETE':
        del Books[book_id]
        return '', 204
    return


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

GET（取得）とDELETE（削除）およびPUT（更新）が実装されています。実際にこのAPIを叩いてみましょう。今回はHTTPieを使用しています。cURLと比較するとJSONのリクエストを非常に簡潔に書けるので、とても便利です。

$ http -b http://127.0.0.1:5000/books/1
{
    "id": 1,
    "published_year": 2003,
    "title": "The Internet Galaxy"
}

$ http -b PUT http://127.0.0.1:5000/books/1 id:=1 published_year:=1995 title="Bowling Alone"
{
    "id": 1,
    "published_year": 1995,
    "title": "Bowling Alone"
}

$ http -b DELETE http://127.0.0.1:5000/books/1
$

問題なく動作していることを確認することができました。実装について、この中で一番複雑な実装なのは、リクエストボディを持ちかつそのバリデーションが必要となるPUTの処理です。このように簡単なAPIであれば、自前でそれらの処理を実装しても大したコストにはなりませんが、多数のAPIや複雑なAPIを実装するときにはすべて自前で実装することは現実的ではありません。そこで、この実装にbravado-coreを利用してみましょう。まず、OpenAPIドキュメントを作成します。

OpenAPIドキュメントの作成

次のようにOpenAPIドキュメントを作成します。ここでは、説明に必要ないプロパティの記述は省いています。また、OpenAPIの最新バージョンはVersion3ですが、bravado-coreはVersion3にはまだ対応していないため、Version2で記述します。

swagger: "2.0"
info:
  version: 1.0.0
  title: Library
  license:
    name: MIT
host: library.example.com
basePath: /
schemes:
  - http
  - https
consumes:
  - application/json
produces:
  - application/json
paths:
  /books/{book_id}:
    parameters:
      - name: book_id
        in: path
        required: true
        description: id of book
        type: integer
    get:
      responses:
        "200":
          description: Book was retrieved successfully
          schema:
            $ref: '#/definitions/Book'
    put:
      parameters:
        - name: params
          in: body
          required: true
          schema:
            $ref: '#/definitions/Book'
      responses:
        "200":
          description: Book was updated successfully
          schema:
            $ref: '#/definitions/Book'
    delete:
      responses:
        "204":
            description: Book was deleted successfully

definitions:
  Book:
    type: object
    required: [id, title, published_year]
    properties:
      id:
        type: integer
      title:
        type: string
      published_year:
        type: integer

bravado-coreを利用した実装

次に、bravado-coreの部分の実装に移ります。bravado-coreにはIncomingRequestという仕組みがあり、このIncomingRequestを継承し、それぞれのWebアプリケーションのリクエストオブジェクトに対するアダプタを実装することで、bravado-coreを利用することができるようになります。例えばFlaskの場合には、次のようになります。

class BravadoRequest(IncomingRequest):
    @property
    def path(self) -> dict:
        return request.view_args

    @property
    def query(self) -> dict:
        return dict(request.args)

    @property
    def form(self) -> dict:
        return request.form

    @property
    def headers(self) -> dict:
        return request.headers

    def json(self) -> dict:
        return request.json

Flaskではrequestに全てのリクエストパラメータが格納されるため、これをIncomingRequestで定義されたインタフェースに沿って実装しています。

これを使用して、リクエストの展開とバリデーションをしてみましょう。bravado-coreを利用するためには、事前にYAML（もしくはJSON）のOpenAPIドキュメントを読み込む必要があります。また、今回はリクエストのUnmarshal用の関数としてbravado-coreで定義されている、unmarshal_requestを使います。この部分を追記し、BravadoRequestクラスも一部修正すると下記のようになります。

import yaml
from bravado_core.spec import Spec
from bravado_core.request import IncomingRequest
from bravado_core.request import unmarshal_request


class OpenAPIError(Exception):
    pass


class OpenAPI:
    def __init__(self, doc_path: str, config: dict = None) -> None:
        with open(doc_path, "r") as fp:
            self._raw_spec: dict = yaml.load(fp)
        self.spec: Spec = Spec.from_dict(self._raw_spec, config=config)

    def unmarshal_request(self) -> dict:
        b_req = BravadoRequest(self)
        operation = self.spec.get_op_for_request(request.method.lower(), b_req.endpoint())
        if not operation:
            raise OpenAPIError('Failed to find proper operation method = {}, endpoint = {}'.format(
                request.method.lower(), b_req.endpoint()
            ))
        return unmarshal_request(b_req, operation)


class BravadoRequest(IncomingRequest):
    def __init__(self, openapi: OpenAPI) -> None:
        self.openapi: OpenAPI = openapi

    def endpoint(self) -> str:
        import re
        flask_path: str = str(request.url_rule)
        spec_path_pattern = re.sub(r'<(?:[a-z]+:)?(\w+)>', r'{\1}', flask_path)

        if self.openapi.spec._request_to_op_map is None:
            self.openapi.spec.get_op_for_request("get", "")

        for method, url in self.openapi.spec._request_to_op_map.keys():
            result = re.match(spec_path_pattern, url)
            if result is not None \
                    and result.group(0) == url \
                    and request.method.lower() == method:
                return url

    @property
    def path(self) -> dict:
        return request.view_args

    @property
    def query(self) -> dict:
        return dict(request.args)

    @property
    def form(self) -> dict:
        return request.form

    @property
    def headers(self) -> dict:
        return request.headers

    def json(self) -> dict:
        return request.json

急に記述が増えました。unmarshal_requestは第1引数にIncomingRequestを継承したクラスのインスタンス、第2引数にOpenAPIドキュメントから取得したリクエストに対応するパスの定義を渡します。この第2パラメータの取得のための記述が増えています。ちなみにunmarshal_requestの中では、文字通りリクエストのUnmarshalingと、OpenAPIドキュメントに従ったリクエストのバリデーションを行ってくれます。それではこれを先程のFlaskアプリケーションに組み込んで書き換えてみましょう。

@app.route('/books/<int:book_id>', methods=['GET', 'PUT', 'DELETE'])
def book(book_id: int):
    openapi = OpenApi('openapi.yaml')
    client_req = openapi.unmarshal_request()

    book_id = client_req['book_id']
    params = client_req['params']
    target = Books.get(book_id)
    if not target:
        return jsonify(error=404, text="No book with book_id: {}".format(book_id)), 404

    if request.method == 'GET':
        resp = attr.asdict(target)
        resp.update({'id': book_id})
        return jsonify(resp)

    elif request.method == 'PUT':
        if book_id != params['id']:
            return jsonify(error=400, text="Bad request"), 400

        target.title = params['title']
        target.published_year = params['published_year']

        resp = attr.asdict(target)
        resp.update({'id': book_id})
        return jsonify(resp)

    elif request.method == 'DELETE':
        del Books[book_id]
        return '', 204
    return

メソッドの開始時に、OpenApiクラスのインスタンスを作成し、unmarashal_requestメソッドをコールしています。このメソッド内部にて、リクエストのバリデーションが行われます。バリデーションに失敗した場合には、jsonschema.exceptions.ValidationErrorがraiseされます。これはbravado-coreのリクエストのバリデーションに、jsonschemaのライブラリを使用しているためです。このエラーを400にマッピングする処理を追加します。

from jsonschema.exceptions import ValidationError

@app.errorhandler(ValidationError)
def validation_error(e: ValidationError):
    app.logger.exception(e)
    return jsonify(error=400, text="Bad request"), 400

いくつかリクエストを送ってみると次のようになります。

$ # 問題ない場合
$ http -b PUT http://127.0.0.1:5000/books/1 id:=1 published_year:=1995 title="Bowling Alone"
{
    "id": 1,
    "published_year": 1995,
    "title": "Bowling Alone"
}

$ # エラーの場合: 必要なプロパティがない（published_yearがない）
$ http -b PUT http://127.0.0.1:5000/books/1 id:=1 title="Bowling Alone"
{
    "error": 400,
    "text": "Bad request"
}

$ # エラーの場合: プロパティの型が正しくない（published_yearが文字列）
$ http -b PUT http://127.0.0.1:5000/books/1 id:=1 published_year=year title="Bowling Alone"
{
    "error": 400,
    "text": "Bad request"
}

このように不正なリクエストを正しく検知できています。

補足

実際のプロジェクトでは、下記のようなデコレータを実装し、これらの処理を簡潔に記述できるようにしています。

def extract_params(func):
    @wraps(func)
    def wrapped(*args, **kwargs):
        openapi = OpenApi('openapi.yaml')
        client_req = openapi.unmarshal_request()
        kwargs.update(client_req)
        return func(*args, **kwargs)
    return wrapped


@app.route('/books/<int:book_id>', methods=['GET', 'PUT', 'DELETE'])
@extract_params
def book(book_id: int, params: dict = None):
    target = Books.get(book_id)
    # 以下略

また、本記事ではご紹介しませんでしたが、bravado-coreにはクエリパラメータやフォームパラメータも展開し、バリデーションをする事が可能です。他にも、以前紹介したカスタムフォーマットの機能を使うことで、リクエストで受け取ったデータをunmarshal_request関数内で自動的に変換できます。

まとめ

bravado-coreを使うことで、リクエストのUnmarshalingやバリデーションを柔軟に実装することが可能です。OpenAPIドキュメントは、このようなbravado-coreの利用の他にも、クライアントアプリケーションや、APIドキュメントの自動生成に利用することができるます。このように非常に効率よく開発をすすめることができるので、API開発者の各位におかれましては、ぜひ導入してみることをオススメします。