OpenAPIの定義を利用するConnexionを触ってみる

2019.12.06

2021.08.12

Fabeee社員ブログ

こんにちは、Fabeeeのミスター器用貧乏ことMAXです。
今回は弊社標準開発言語でありボクも大好きなPython、そのフレームワークの一つであるConnexionをご紹介しようと思います。

突然ですがみなさんOpenAPI使ってますか？細かい説明や定義は公式をご覧いただければと思うのですが、簡単に説明すると「REST APIの定義をテキストベースで記述する仕様」です。現在はVer.3.0が公開されています。テキストベースなので変更管理できる、フロントエンド/サーバサイドの認識齟齬うまれにくい等メリットも多く便利ですよね。
connexionはこのOpenAPI仕様で書かれた定義ファイル（.yamlファイル）を使って開発、動作するFlaskベースのフレームワークです。

特徴として、以下が挙げられています。

仕様に基づいたリクエスト、エンドポイントのパラメータ自動検証
Swagger ConsolというWeb UIを提供し、ライブドキュメンテーションやエンドポイントの呼び出しが可能
OAuth2トークンベースの認証処理
APIのバージョニングをサポート

また、「Payloadの自動シリアライズをサポート。APIがJSONを返す仕様の場合、Connexionは値を自動的にシリアライズしHTTPヘッダへ正しいcontent typeをセットする」ともあります。
なんだかすごそうな感じがしませんか？
それでは動かしてみましょう！！

connexionインストール

$ pip install connexion[swagger-ui]

作成

各ファイルを作成します。今回はGETメソッドを受け付ける/hogeというエンドポイントをサンプルとして作成しています。

構成

(project_root)
├ hoge.py
└ openapi/

└ spec.yaml

定義ファイル

openapi: 3.0.0
info:
  title: connexion sample
  description: OpenAPI and connexion sample
  version: 1.0.0
servers:
  - url: http://localhost:8080
    description: sample
paths:
  /hoge:
    get:
      operationId: hoge.get_sample
      summary: hoge sample
      description: hoge get sample
      responses:
        '200':
          description: getのサンプル
          content:
            application/json:
              schema:
                type: string
                example: "hello hoge sample!!"
tags:
  - name: hoge
    description: サンプルAPIです。

実行ファイル

import connexion def get_sample(**kwargs):   return {'status': 'hoge OK!!'} options = {"swagger_ui": True} app = connexion.FlaskApp(__name__,specification_dir='openapi/', options=options) app.add_api('spec.yaml') app.run(port=8080)

実行

$ python hoge.py

以下のようなレスポンスが返ってくると思います。

* Serving Flask app "hoge" (lazy loading) * Environment: production WARNING: This is a development server. Do not use it in a production deployment. Use a production WSGI server instead. * Debug mode: off * Running on http://0.0.0.0:8080/ (Press CTRL+C to quit)

ためにしAPIへリクエストしてみます。

$ curl -X GET http://localhost:8080/hoge

これで以下のようなレスポンスが返れば正常に動作しています。

{ "status": "hoge OK!!" }

また、http://localhost:8080/ui/へアクセスすると以下の様にSwagger UIが表示されます。

まとめ

非常に駆け足でしたがサンプル用の簡単なAPIを定義ファイルと本当に少ないコードで動作させることができました。
個人開発でサクッとAPIを作りたい場合や、Django + Django REST Frameworkだと厚すぎるといった場合の選択肢になるのではないでしょうか。
SES/受託開発のご依頼についてはこちら

OpenAPI