OpenAPIを利用するための色々なツール
ライブラリの具体的な紹介に入る前に、少しOpenAPIツール全体についてご紹介いたします。このようなツールは多数開発されており、Swaggerの公式サイトから確認することができます（Python以外の言語のツールも多数あります）。ただし、ここに掲載されているツールにはあまりメンテされていないものあるので、使う前に確認が必要です。
ちなみに、前回の記事でも書きましたがOpenAPI Spec（OAS）の最新バージョンであるv3.0.0が2017年7月にリリースされましたが、既存のツールでv3.0.0に対応しているものは少ないです。
本記事でご紹介するbravado-coreもこのページの中で紹介されています。というわけで、本題のbravado-coreの内容紹介に入りましょう。
bravado-core
https://github.com/Yelp/bravado-core
何のライブラリ？
bravado-coreは、OpenAPIを利用してAPIに関するPythonコード（クライアント／サーバ）を自動生成するライブラリです。自動生成するといっても、前回ご紹介したSwagger Codegenのように静的なPythonファイルを生成するものではなく、プログラムの実行時にPythonのクラスを動的に生成するタイプのライブラリです。
Swagger Codegenで、PythonのAPIクライアントのコードは自動生成することが可能ですが、サーバサイドのコードは生成することができない（対応しているジェネレータがない）ため、カブクではPythonのサーバサイドの実装の一部にこのbravado-coreを使用しています。
bravado-coreの特徴
bravado-coreには下記のような特徴があります。
- オブジェクトのバリデーションが可能
- オブジェクトのMarshalingおよびUnmarshalingが可能
- 自動フォーマット変換が可能
- 特定のフレームワークに依存しない
順を追って詳しくみてみましょう。
1. オブジェクトのバリデーションが可能
bravado-coreでは、オブジェクト（たとえばクライアントから送られたRequest Bodyの内容）をOpenAPIドキュメントの定義に従ってバリデーションすることができます。
例えば、次のようなオブジェクトを考えてみましょう。このオブジェクトは、Bookという名を持ち、3つのプロパティとしてid(integer)、titile(string)、 author(string)を持ちます。また、idは必須なプロパティです。
Book:
type: object
required: [id]
properties:
id:
type: integer
title:
type: string
author:
type: stringあるdict型の値が与えられた時に、その値がこのオブジェクトの定義に従っているかどうかのバリデーションを行うことが可能です。実装は次のようになります。
import yaml
from bravado_core.spec import Spec
from bravado_core.validate import validate_schema_object
# 1
with open('openapi.yaml', 'r') as f:
raw_spec = yaml.load(f)
# 2
spec = Spec.from_dict(raw_spec)
# 3
book = raw_spec['definitions']['Book']
# 4
validate_schema_object(spec, book, target)
#1では、事前に作成したOpenAPIドキュメントをロードします。#2でbravado-coreのSpecオブジェクトを作成します。#3でOpneAPIドキュメントのBookオブジェクトの定義を取得します。#4でバリデーションを実行します。このコードでは、targetという変数に格納された値のバリデーションを実行しています。ここで、targetに格納する値としては、例として外部から受信したJSONをロードしたdict型の変数を想定しています。
このvalidate_schema_objectというメソッドを実行した時に、もしバリデーションに問題があった場合には、例外が発生します。実例を見てみましょう。
例えば、次のように空のdict値を与えると、必須プロパティであるidが定義されていないため、例外が発生します。
validate_schema_object(spec, book, {})jsonschema.exceptions.ValidationError: 'id' is a required property
Failed validating 'required' in schema:
{'properties': {'author': {'type': 'string'},
'id': {'type': 'integer'},
'release_date': {'format': 'date', 'type': 'string'},
'title': {'type': 'string'}},
'required': ['id'],
'type': 'object',
'x-model': 'Book'}
On instance:
{}メッセージは「必須プロパティのidが定義されていない」ということを示しており、正しくバリデーションができていることが分かります。
別のケースを考えてみましょう。次のように、型が異なる値を与えてみます。titleプロパティは文字列型として定義されていますが、数値として与えてみると、やはり例外が発生します。
validate_schema_object(spec, book, {"id": 1, "title": 1})jsonschema.exceptions.ValidationError: 1 is not of type 'string'
Failed validating 'type' in schema['properties']['title']:
{'type': 'string'}
On instance['title']:
1メッセージは「1は文字列ではない」ということを示しており、やはり正しくバリデーションができていることを確認できました。
このようにOpenAPIドキュメントを書くだけで、オブジェクトのバリデータを作成できるため非常に便利です。
2. オブジェクトのMarshalingおよびUnmarshalingが可能
3. 自動フォーマットの変換が可能
ここで述べるMarshalingとは、Pythonオブジェクトを外部へ送信できる形式に変換すること、Unmarshalingはその逆の操作を指します。
もう少し具体的なイメージとしては、アプリケーション内部のデータをクライアント（サーバ）へ送出できる状態に変換することをMarshaling、クライアント（サーバ）から受け取ったリクエストをPythonの内部形式に変換することをUnmarshalingと指すと捉えていただければ問題ありません。
またこれらの変換を行う時に、OpneAPIで定義されたプロパティのフォーマットに従って、自動でデータのフォーマット変換を行うことが出来ます。
具体例を見てみましょう。
ここで、自動変換について確認するために、Bookオブジェクトの定義を次のように更新します。ここでは、新しくrelease_dateという、date（日付）のformatを持つstring型のプロパティを追加しています。
Book:
type: object
required: [id]
properties:
id:
type: integer
title:
type: string
author:
type: string
release_date:
type: string
format: date
このBookオブジェクトに対して、bravado_core.marshal_schema_objectという関数を使用して、Marshalingしてみましょう。specオブジェクトに定義されたBookクラスを使用して変数を作成し、その値をメソッドに渡します。
Book = spec.definitions['Book']
book_obj = Book(id=1, title="Merchant of Venice",
author="William Shakespeare",
release_date=datetime.date(2017, 7, 11))
book_dict = marshal_schema_object(spec, book, book_obj)
print(book_dict)すると、次のように出力されます。
{'release_date': '2017-07-11', 'title': 'Merchant of Venice', 'id': 1, 'author': 'William Shakespeare'}
JSONに変換可能なdict型の値に変換することができました。また、datetime.date型で渡されたrelease_dateは、日付を表す文字列に自動変換されることが確認できました。
同様にUnmarshalingをしてみます。bravado_core.unmarshal_shcema_objectという関数に、unmarshalしたいdict型の値を渡し、実行します。
book_obj = unmarshal_schema_object(
spec, book,
{"id": 1,
"title": "Merchant of Venice",
"author": "William Shakespeare",
"release_date": "2017-07-11"})
print(book_obj)すると、次のように出力されます。
Book(author='William Shakespeare', id=1, release_date=datetime.date(2017, 7, 11), title='Merchant of Venice')dict型の変数からPythonオブジェクトに変換されることを確認できました。また日付を表す文字列は、datetime.date型の値に変換されることもわかりました。
このようにbravado-coreがデフォルトでフォーマット変換に対応している形式としては、下記の形式があります。
bytedatedoubledate-timefloatint32int64
ちなみに、これらの形式はOpenAPI Spec上で定義されている形式です。これらの変換は、bravado-coreのformatter.pyで定義されています。
またbravado-coreでは、独自のformat変換を定義することも可能です。これによってアプリケーション特有のフォーマット変換（たとえばIPアドレスの変換、ストレージパスの変換など）も実装できるでしょう。
4.特定のフレームワークに依存しない
PythonでOpenAPI Specに対応しているツールには、特定のフレームワークに依存したツールが多く存在します。例えばDjango REST SwaggerはDjango REST Frameworkを使用しているプロジェクト向けのライブラリですし、flask-swaggerはFlask向けのライブラリです。もちろんこれらのライブラリは、対応してるフレームワーク以外では使用することができません。
bravado-coreは、特定のフレームワークに依存していないため、どのフレームワークでも使用することができます。プロジェクトに合わせた柔軟なカスタマイズが可能ですので、各プロジェクトに合わせた利用ができることも大きな利点だと考えています。
本記事で紹介したbravado-coreの機能は、ほんの一部です。残念なことにbravado-coreのドキュメントが余り充実していないのですが、使い方のサンプル例をこちらで紹介していますので、是非参考にしてみて下さい。また、別のブログの記事でカブクの内部でどのように使用しているかのより具体的な例をご紹介する予定です。
最後に
PyConJP2017にて、この辺の内容について講演させていただきます（『OpenAPIを利用したPythonWebアプリケーション開発』, 2017年9月9日10:55~11:25, room202)。OpenAPIを使用したプロジェクト事例についてもご紹介する予定ですので、ご興味ある方は是非いらしてください！
