swagger-codegenを使ってpython-flaskのモックサーバーを秒で立てたい。

9088 ワード
Python swagger REST-API swagger-codegen Python テキストリンク

はじめに

業務の中でWebサーバーなんぞ詳しくないのに、
PoC用にWebサーバーを立てろ(しかも秒で)と言われた経験がある方にswagger-codegenをご紹介します。
（秒では立てられないかもしれませんが、API仕様さえyamlで書ければ簡単にサーバーまで立てられます。）

swagger-codegenについて

swagger-codegenはYAML(or JSON)でAPI仕様を定義すると、
そのAPI定義通りにモックサーバーを作り、
さらに、以下のようにそのAPIを叩けるブラウザUI画面を作成できます。

使用環境

  • OS ... Windows 10 Home(64bit)
  • Python ... conda環境
  • その他、JREが必要

JREのインストール

JREがない場合は以下よりダウンロード＆インストールをする。
- https://www.java.com/ja/download/manual.jsp

swagger-codegen-cli.jarの取得

mavenのレポジトリから取得する。
- https://repo1.maven.org/maven2/io/swagger/

今回は以下の2.4.15を使用した。
- https://repo1.maven.org/maven2/io/swagger/swagger-codegen-cli/2.4.15

API仕様をswagger.yamlに定義

API仕様を定義してあげると、その定義に沿ってモックサーバーができます。
以下のようなファイルをどこか適当に作成します。

swagger.yaml
swagger: "2.0"
info:
  description: "これはペットストアに関するAPIです。"
  version: "1.0.0"
  title: "Petstore API"
  termsOfService: "http://swagger.io/terms/"
  contact:
    email: "[email protected]"
  license:
    name: "Apache 2.0"
    url: "http://www.apache.org/licenses/LICENSE-2.0.html"
paths:
  /pet/{petId}:
    get:
      summary: "ペット情報API"
      description: "指定されたpetIdの情報を返します"
      parameters:
      - name: "petId"
        in: "path"
        description: "取得したいペットのID"
        required: true
        type: "integer"
        format: "int64"
      responses:
        200:
          description: "成功時のレスポンス"
          schema:
            type: "object"
            properties:
              id:
                type: "integer"
                format: "int64"
              name:
                type: "string"
                example: "doggie"

swagger.yml内の記述の意味は以下をご参考にしてください。
- https://qiita.com/rllllho/items/53a0023b32f4c0f8eabb

モックサーバーを作成

今回は慣れ親しんだpythonを使いたいので、pytoh-flaskでモックサーバーを作成します。

> java -jar {ダウンロードしたjarファイル} generate -i swagger.yaml -l python-flask -o test-server

-lオプションを変えればGoでもNode.jsでもRuby on Railsでもなんでも作れます。
他に-lオプションに何があるかは以下を参考にしてください。
- https://github.com/swagger-api/swagger-codegen/wiki/Server-stub-generator-HOWTO

作成されたフォルダ構成

python-flaskの場合、こんな感じでモックサーバーができます。
Dockerfileもできていますので、Dockerコンテナにすることも可能です。

> tree server
server
├── Dockerfile
├── README.md
├── git_push.sh
├── requirements.txt
├── setup.py
├── swagger_server
│   ├── __init__.py
│   ├── __main__.py
│   ├── controllers
│   │   ├── __init__.py
│   │   └── default_controller.py
│   ├── encoder.py
│   ├── models
│   │   ├── __init__.py
│   │   ├── base_model_.py
│   │   └── inline_response200.py
│   ├── swagger
│   │   └── swagger.yaml
│   ├── test
│   │   ├── __init__.py
│   │   └── test_default_controller.py
│   └── util.py
├── test-requirements.txt
└── tox.ini

この中で、実際の処理を記載するのは、default_controller.pyのpet_pet_id_getの部分になります。

default_controller.py
import connexion
import six

from swagger_server.models.inline_response200 import InlineResponse200  # noqa: E501
from swagger_server import util


def pet_pet_id_get(petId):  # noqa: E501
    """ペット情報API

    指定されたpetIdの情報を返します # noqa: E501

    :param petId: 取得したいペットのID
    :type petId: int

    :rtype: InlineResponse200
    """
    return 'do some magic!'

Windows上のconda環境で動かしてみる。

必要なパッケージをインストールします。
swagger-codegenによって作られた環境にはpipのrequirements.txtしか書いていませんが、
conda環境では以下をインストールすれば動かすことができます。

> conda install connexion
> conda install swagger-ui-bundle

起動します。

> cd test-server
> python -m swagger_server

以下にブラウザからアクセスして画面が見えたら起動できています。
- http://localhost:8080/ui/

以上、お疲れさまでした！