OpenAPIを使ってみる(1) Pythonでテストサーバーを立ち上げる

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)を作成する。

次回は「OpenAPIを使ってみる(2) Androidアプリ(Kotlin)を作成する」。

コメントを残す

メールアドレスが公開されることはありません。 が付いている欄は必須項目です

このサイトはスパムを低減するために Akismet を使っています。コメントデータの処理方法の詳細はこちらをご覧ください