OpenAPIを使ってPythonでテストようのサーバーを立ち上げるところまでやってみる。
次回は「OpenAPIを使ってみる(2) Androidアプリ(Kotlin)を作成する」。
環境は以下の通り。
- macOS Monterey(12.5)
- Python 3.10
- インストールしていない場合は「brew install python3」でインストールする。
~/development/opemapi_sampleフォルダーを作成する、このフォルダーの中で作業する。
開発環境の構築
Visuau Studio Codeに以下の拡張機能をインストールする。
- OpenAPI (Swagger) Editor
- 「command+shift+P」→「Preview Swagger」で、右パネルにプレビューを表示する。
- 左パネルのOpenAPIを開くと各項目が整理されて表示される。
- OpenApi Snippets
- 入力中に補完が効く。
- openapi-lint
- 入力間違いの箇所にエラーが表示される
APIの作成
次のようなAPIを作成する。
- http://192.168.10.109:8080/v1/users
- ユーザー概要一覧を取得する
- パラメータ
- クエリー文字列でpageを受け取る。
- 返り値
- {id:ユーザーID, name:ユーザー名}の配列
- http://192.168.10.109:8080/v1/users/{userId}
- ユーザー詳細(id,name)を取得する
- パラメータ
- URLでユーザーIDを受け取る。
- 返り値
- {id:ユーザーID, name:ユーザー名, birthday:生年月日}
openapiフォルダーを作成し、openapi.ymlを作成する。
openapi_sample/
openapi/
openapi.yml
openapi.ymlを編集する。
openapi: 3.0.3
info:
title: "Sample User List App"
description: This is a sample app
version: "1.0.0"
servers:
- url: http://192.168.10.109:8080/v1
description: Development server
paths:
/users:
get:
summary: ユーザー一覧
operationId: listUsers
tags:
- users
parameters:
- in: query
name: page
description: ページ番号
example: 1
required: false
schema:
type: integer
responses:
'200':
description: Return all users
content:
application/json:
schema:
type: array
items:
$ref: "#/components/schemas/SimpleUser"
default:
description: Unexpected error
/users/{userId}:
get:
summary: ユーザーを取得する
operationId: getUserById
tags:
- users
parameters:
- in: path
name: userId
description: ユーザーID
example: 1
required: true
schema:
type: integer
responses:
'200':
description: A user
content:
application/json:
schema:
$ref: "#/components/schemas/User"
default:
description: Unexpected error
components:
schemas:
SimpleUser:
properties:
id:
type: integer
description: ユーザーID
name:
type: string
description: ユーザー名
User:
properties:
id:
type: integer
description: ユーザーID
name:
type: string
description: ユーザー名
birthday:
type: string
description: 生年月日
example: '2001-02-03'
OpenAPI Generatorの導入
OpenAPI Generatorを導入する。
macOSの場合は、Homebrewを使ってインストールする。
# インストール
% brew install openapi-generator
# 確認
% openapi-generator version
6.0.1
その他のOSの場合は公式サイトに書かれているインストール方法を参考にする。
Python Server
Python Serverを作成する
openapi.ymlのあるフォルダーで、以下のコマンドを実行する。
openapi-generator generate -i openapi.yml -g python-flask -o server
serverフォルダーに、PythonのFlaskを使ったStub Serverのファイル一式が作成される。
Flaskのバージョンが古くエラーになったため、Flaskのバージョンを更新する。
server/requirements.txtを編集する。
Flask == 2.1.3
Stub Serverをを起動する
cd server
pip3 install -r requirements.txt
python3 -m openapi_server
または
cd server
docker build -t openapi_server .
docker run -p 8080:8080 openapi_server
http://192.168.10.109:8080/v1/ui/にアクセスして、API仕様書が表示されることを確認する。
APIの返り値を設定する
server/openapi_server/controllers/users_controller.pyを編集して、返り値を設定する。
from flask import jsonify
def get_user_by_id(user_id): # noqa: E501
match user_id:
case 1:
return jsonify({'id':1,'name':'Alice','birthday':'2001-02-01'})
case 2:
return jsonify({'id':2,'name':'Bob','birthday':'2001-02-02'})
case 3:
return jsonify({'id':3,'name':'Carol','birthday':'2001-02-03'})
case 4:
return jsonify({'id':4,'name':'Dave','birthday':'2001-02-04'})
return 'User not found.', 404
def list_users(page=None): # noqa: E501
if page == 2:
return jsonify(({'id':4, 'name':'Dave'}))
else:
return jsonify(({'id':1,'name':'Alice'}, {'id':2, 'name':'Bob'}, {'id':3,'name':'Carol'}))
http://192.168.10.109:8080/v1/usersにアクセスして、ユーザー一覧のJSONが返されることを確認する。
http://192.168.10.109:8080/v1/users/1にアクセスして、ユーザーのJSONが返されることを確認する。
開発の準備ができたので、次回はAndroidアプリ(Kotlin)やiOSアプリ(Swift)を作成する。