bravado-coreによるOpenAPIを利用したPythonアプリケーション開発

2017/09/08
このエントリーをはてなブックマークに追加
ソフトウェアエンジニアの和田です。前回の記事ではOpenAPIの概要について記述いたしました。今回の記事では、Yelpが作成しているbravado-coreというPythonライブラリを使用してよりOpenAPIを使用した場合のPythonにおける具体的な実装例をご紹介したいと思います。

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には下記のような特徴があります。

  1. オブジェクトのバリデーションが可能
  2. オブジェクトのMarshalingおよびUnmarshalingが可能
  3. 自動フォーマット変換が可能
  4. 特定のフレームワークに依存しない

順を追って詳しくみてみましょう。

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がデフォルトでフォーマット変換に対応している形式としては、下記の形式があります。

  • byte
  • date
  • double
  • date-time
  • float
  • int32
  • int64

ちなみに、これらの形式は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を使用したプロジェクト事例についてもご紹介する予定ですので、ご興味ある方は是非いらしてください!

その他の記事

Other Articles

2019/04/16
C++のenable_shared_from_thisを使う

2019/04/12
OpenAPI 3 ファーストな Web アプリケーション開発(Python で API 編)

2019/04/08
WebGLでレイマーチングを使ったCSGを実現する

2019/04/02
『エンジニア採用最前線』に感化されて2週間でエンジニア主導の求人票更新フローを構築した話

2019/03/29
その1 Jetson TX2でk3s(枯山水)を動かしてみた

2019/03/27
任意のブラウザ上でJestで書いたテストを実行する

2019/02/08
TypeScript で “radian” と “degree” を間違えないようにする

2019/02/05
Python3でGoogle Cloud ML Engineをローカルで動作する方法

2019/01/18
SIGGRAPH Asia 2018 参加レポート

2019/01/08
お正月だョ!ECMAScript Proposal全員集合!!

2019/01/08
カブクエンジニア開発合宿に行ってきました 2018秋

2018/12/25
OpenAPI 3 ファーストな Web アプリケーション開発(環境編)

2018/12/23
いまMLKitカスタムモデル(TF Lite)は使えるのか

2018/12/21
[IoT] Docker on JetsonでMQTTを使ってCloud IoT Coreと通信する

2018/12/11
TypeScriptで実現する型安全な多言語対応(Angularを例に)

2018/12/05
GASでCompute Engineの時間に応じた自動停止/起動ツールを作成する 〜GASで簡単に好きなGoogle APIを叩く方法〜

2018/12/02
single quotes な Black を vendoring して packaging

2018/11/14
3次元データに2次元データの深層学習の技術(Inception V3, ResNet)を適用

2018/11/04
Node Knockout 2018 に参戦しました

2018/10/24
SIGGRAPH 2018参加レポート-後編(VR/AR)

2018/10/11
Angular 4アプリケーションをAngular 6に移行する

2018/10/05
SIGGRAPH 2018参加レポート-特別編(VR@50)

2018/10/03
Three.jsでVRしたい

2018/10/02
SIGGRAPH 2018参加レポート-前編

2018/09/27
ズーム可能なSVGを実装する方法の解説

2018/09/25
Kerasを用いた複数入力モデル精度向上のためのTips

2018/09/21
競技プログラミングの勉強会を開催している話

2018/09/19
Ladder Netwoksによる半教師あり学習

2018/08/10
「Maker Faire Tokyo 2018」に出展しました

2018/08/02
Kerasを用いた複数時系列データを1つの深層学習モデルで学習させる方法

2018/07/26
Apollo GraphQLでWebサービスを開発してわかったこと

2018/07/19
【深層学習】時系列データに対する1次元畳み込み層の出力を可視化

2018/07/11
きたない requirements.txt から Pipenv への移行

2018/06/26
CSS Houdiniを味見する

2018/06/25
不確実性を考慮した時系列データ予測

2018/06/20
Google Colaboratory を自分のマシンで走らせる

2018/06/18
Go言語でWebAssembly

2018/06/15
カブクエンジニア開発合宿に行ってきました 2018春

2018/06/08
2018 年の tree shaking

2018/06/07
隠れマルコフモデル 入門

2018/05/30
DASKによる探索的データ分析(EDA)

2018/05/10
TensorFlowをソースからビルドする方法とその効果

2018/04/23
EGLとOpenGLを使用するコードのビルド方法〜libGLからlibOpenGLへ

2018/04/23
技術書典4にサークル参加してきました

2018/04/13
Python で Cura をバッチ実行するためには

2018/04/04
ARCoreで3Dプリント風エフェクトを実現する〜呪文による積層造形映像制作の舞台裏〜

2018/04/02
深層学習を用いた時系列データにおける異常検知

2018/04/01
音声ユーザーインターフェースを用いた新方式積層造形装置の提案

2018/03/31
Container builderでコンテナイメージをBuildしてSlackで結果を受け取る開発スタイルが捗る

2018/03/23
ngUpgrade を使って AngularJS から Angular に移行

2018/03/14
Three.jsのパフォーマンスTips

2018/02/14
C++17の新機能を試す〜その1「3次元版hypot」

2018/01/17
時系列データにおける異常検知

2018/01/11
異常検知の基礎

2018/01/09
three.ar.jsを使ったスマホAR入門

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

2017/12/15
WebAssembly(wat)を手書きする

2017/12/14
AngularJS を Angular に移行: ng-annotate 相当の機能を TypeScrpt ファイルに適用

2017/12/08
Android Thingsで4足ロボットを作る ~ Android ThingsとPCA9685でサーボ制御)

2017/12/06
Raspberry PIとDialogflow & Google Cloud Platformを利用した、3Dプリンターボット(仮)の開発 (概要編)

2017/11/20
カブクエンジニア開発合宿に行ってきました 2017秋

2017/10/19
Android Thingsを使って3Dプリント戦車を作ろう ① ハードウェア準備編

2017/10/13
第2回 魁!! GPUクラスタ on GKE ~PodからGPUを使う編~

2017/10/05
第1回 魁!! GPUクラスタ on GKE ~GPUクラスタ構築編~

2017/09/13
「Maker Faire Tokyo 2017」に出展しました。

2017/09/11
PyConJP2017に参加しました

2017/08/23
OpenAPIのご紹介

2017/08/18
EuroPython2017で2名登壇しました。

2017/07/26
3DプリンターでLチカ

2017/07/03
Three.js r86で何が変わったのか

2017/06/21
3次元データへの深層学習の適用

2017/06/01
カブクエンジニア開発合宿に行ってきました 2017春

2017/05/08
Three.js r85で何が変わったのか

2017/04/10
GCPのGPUインスタンスでレンダリングを高速化

2017/02/07
Three.js r84で何が変わったのか

2017/01/27
Google App EngineのFlexible EnvironmentにTmpfsを導入する

2016/12/21
Three.js r83で何が変わったのか

2016/12/02
Three.jsでのクリッピング平面の利用

2016/11/08
Three.js r82で何が変わったのか

2016/12/17
SIGGRAPH 2016 レポート

2016/11/02
カブクエンジニア開発合宿に行ってきました 2016秋

2016/10/28
PyConJP2016 行きました

2016/10/17
EuroPython2016で登壇しました

2016/10/13
Angular 2.0.0ファイナルへのアップグレード

2016/10/04
Three.js r81で何が変わったのか

2016/09/14
カブクのエンジニアインターンシッププログラムについての詩

2016/09/05
カブクのエンジニアインターンとして3ヶ月でやった事 〜高橋知成の場合〜

2016/08/30
Three.js r80で何が変わったのか

2016/07/15
Three.js r79で何が変わったのか

2016/06/02
Vulkanを試してみた

2016/05/20
MakerGoの作り方

2016/05/08
TensorFlow on DockerでGPUを使えるようにする方法

2016/04/27
Blenderの3DデータをMinecraftに送りこむ

2016/04/20
Tensorflowを使ったDeep LearningにおけるGPU性能調査

→
←

関連職種

Recruit

バックエンドエンジニア(Python・Go)

業務内容

当ポジションは弊社Webサービスのバックエンド機能設計及び実装を担当します。 サービス毎の開発チームで2週間スプリントのスクラム開発を実施しています。 週次で開発チームミーティングを実施し、実装設計の相談や工数見積もりを行います。 全ての開発コードはレビューと自動テストによって品質を保っています。 また、リファクタリングやフレームワークのバージョンアップも開発フローに組込み、技術的負債を放置しない開発を目指しています。

フロントエンドエンジニア(TypeScript)

業務内容

当ポジションは弊社Webサービスのフロントエンド機能設計及び実装を担当します。 サービス毎の開発チームで2週間スプリントのスクラム開発を実施しています。 週次で開発チームミーティングを実施し、実装設計の相談や工数見積もりを行います。 全ての開発コードはレビューと自動テストによって品質を保っています。 また、リファクタリングやフレームワークのバージョンアップも開発フローに組込み、技術的負債を放置しない開発を目指しています。

機械学習エンジニア

業務内容

センサーデータの分析モデルの調査・研究・開発。 Kabuku Connectの製造データ(3D、2D)から情報を抽出するモデルの構築。 データの前処理や学習、ハイパーパラメータチューニング、獲得モデルの評価、プロダクションのデータパイプラインとの連携をお願いします。

インターン(Webエンジニア)

業務内容

業務から独立した、調査・研究系のタスクをおまかせしています。コードレビュー、 社内での報告会、 ブログ記事執筆を通して着実にスキルアップしていただくことを目指しています。 (希望があれば、プロダクトの開発業務もおまかせします。)

→
←

お客様のご要望に「Kabuku」はお応えいたします。
ぜひお気軽にご相談ください。

お電話でも受け付けております
03-6380-2750
営業時間:09:30~18:00
※土日祝は除く