OpenAPIとSchemathesisの紹介

OpenAPIに従ってrest apiへリクエストを投げるパッケージ
dev
openapi
Author

Masaya Kameyama

Published

May 21, 2023

Introduction

SchemathesisとはREST APIのtest toolのひとつでopenapi.jsonが与えられた場合それをもとにtest caseを自動生成してリクエストを投げてテストを行ってくれる. 現在のプロジェクトではfastapiを使ってREST APIを開発しているのでopenapi.jsonも自動生成してくれる. APIをクラウドにdeployしたあとリクエストを投げてテストを行いたいがtestコードを書くのが面倒だったのでOpenAPI toolsからいくつか試して一番良かったのがこれである.

解説

OpenAPI Specification (OAS)とはREST APIのための機械で読み取り可能なインターフェース定義可能な言語のこと. 言い換えるとAPIの仕様書の規格. 以前はSwagger Specificationという名前で知られていた. Swaggerは2010年から開発が始まり, 2016年にプロジェクトが分かれOpenAPI Initiativeで管理されるようになった. 一方swaggerはAPI開発のためのOSSツール群でOASを通じてAPI開発をサポートしてくれる. OASはjsonやymlで書くことがきる. OASの作法に乗っ取って仕様を書いておけば, 例えばswagger UIから利用可能なendpoints, parameters, authentificationなどのドキュメントを生成することができる.

参考

fastAPI

チームで利用しているfastAPIにはopenAPIを利用した機能がいくつかあり, 例えばlocalでAPIを起動するとhttp://127.0.0.1:8000/docs にアクセスすることでswagger UIによってinteractiveなドキュメントを参照することができる.

現在fastAPIが利用しているOSAはversion 3.0.2である. またAPI経由でopenapi.josnが得られるのでこれを利用してAPIのテストを作成したい. ここではCI/CD用にAPIを起動すれば勝手にそのendpointからリクエスト例を取ってきてリクエストを投げるようにしたい. OpenAPI toolsからいくつか試してみた.

step ci

APIをtestするOSSのtool. OSAからtest用のworkflowを自動生成してtestを実行できる. step ciにはfastapiのintegration機能ある(が別にintegrationしていないと思う):

stepci generate http://127.0.0.1:8000/openapi.json

ただしこうしてできるworkflow.ymlは文字列がラテン語で生成される箇所がある. これはopenapi.jsonの作りが悪いせいである.

stepci runの実行:

stepci run workflow.yml

ⓘ  Anonymous usage data collected. Learn more on https://step.ci/privacy

 PASS  Default

Tests: 0 failed, 1 passed, 1 total
Steps: 0 failed, 0 skipped, 1 passed, 1 total
Time:  7.16s, estimated 7s

Workflow passed after 7.16s
Give us your feedback on https://step.ci/feedback

generateのオプションでexampleを使う様に指定できるが機能しなかった.

Schemathesis

使い方は公式のドキュメントを読んで欲しいが

schemathesis run http://localhost/openapi.json --hypothesis-phases=explicit -H 'hoge:foo'

でexampleのリクエストを使ってtestを行ってくれる. また仕事ではalbの関係でheaderも付ける必要があったがそれも問題なかった. dockerのimageも提供されているのでci/cdに組み込んだりdocker-composeでtestを行うのも簡単だった.

Back to top