SwaggerEditorでAIPを設計してみる

SwaggerEditorを使ってAPIの設計を行ったのでメモ

この記事で行っていること

• SwaggerEditorを使ってAPI設計
• SwaggerCodegenでPython-Flaskコードを生成
• docker-composeで起動、SwaggerUIよりお試しリクエスト

Swaggerとは

API開発をする際に使えるツールが詰まったもの。 以下のツールがオープンソースで誰でも使える

ツール
Swagger Codegen	OpenAPIの定義からサーバ、クライアントのコードを生成する
Swagger Editor	OpenAPIの仕様で、APIを設計するエディタ
Swagger UI	設計したAPIを表示するビュワー。実際にリクエストを送り、応答を確認できる。

OpenAPIとは

• OpenAPI Initiative(OAI)というコミュニティが定めた、API仕様を記述する標準フォーマット
• JSON、YAMLの二つの形式で表すことが可能
• ファイル名デフォルトはopenapi.jsonかopenapi.yaml

用語の整理

• OAI = OpenAPI Initiative というコミュニティ、団体
• OAS = OpenAPI Specification OpenAPIの仕様
• swagger2.0 = v2.0のOASフォーマット
• OAS3.0 = v3.0のOASフォーマット

Swager Editorを使ってみる

書き方はこちらを参考に、 簡単なAPIを設計
OpenAPIで定義できる項目が多くて大変💦💦

今回設計するAPI
- BaseURL : http://localhsot:5000/api/v1 - Version : 0.0.1

エンドポイント一覧

メソッド	パス
GET	/users	すべてのユーザ情報を取得
GET	/users/{id}	指定idのユーザ情報を取得
POST	/users	新規のユーザを登録

openapi.yaml

openapi: 3.0.0
info:
  title: "初めてのSwaggerEditor"
  description: "初めてSwaggerEditorを使って、API設計してみる"
  termsOfService: ""
  version: "0.0.1"
servers:
  - url: "http://localhost:8080/api/v1"
    description: "ユーザ情報を取得するAPIサーバ"
paths:
  /users:
    summary: "Get Users"
    description: "Usersに関する操作"
    get:
      summary: "Get Users"
      description: "全てのユーザを取得します"
      responses:
        200:
          description: "全てのユーザを返す"
          content:
            application/json:
              schema:
                type: string
              examples:
                users:
                  value: [{ "id":1, "name":"Jon", "age":19 },{ "id":2, "name":"Mike", "age":21 }]          
    post:
      summary: "Add User"
      description: "新しいユーザを追加します"
      operationId: "addUser"
      requestBody:
        required: true
        content:
          application/x-www-form-urlencoded:
            schema:
              properties:
                name:
                  description: "ユーザの名前"
                  type: string
                age:
                  description: "ユーザの年齢"
                  type: integer
              required:
                - "name"
                - "age"
      responses:
        201:
          description: "正常にユーザを追加しました"
        400:
          description: "不正なリクエストです"
  /users/{user_id}:
    parameters:
    - name: "user_id"
      in: path
      required: true
      description: "userId"
      schema:
        type: integer
    get:
      summary: "Get One User"
      description: "1人のユーザを取得します"
      responses:
        200:
          description: "1人のユーザを返す"
          content:
            application/json:
              schema:
                type: string
              examples:
                user:
                  value: {"id":1,"name":"Jon","age":19}                  

Swagger Codegenでコード生成

今回は、Python Flask でコードを生成してみる
タブからの[Generate Server]⇒[python-flask] を選択

生成されたファイル
選択していないが、Python3.6で作成された
コードはAPIサーバの基本部分のみなので、実際に使用する場合はcontroller.py などに追加する必要がある

swagger_server
│  .dockerignore
│  .gitignore
│  .swagger-codegen-ignore
│  .travis.yml
│  Dockerfile
│  git_push.sh
│  README.md
│  requirements.txt
│  setup.py
│  test-requirements.txt
│  tox.ini
│
├─.swagger-codegen
│      VERSION
│
└─swagger_server
    │  encoder.py
    │  type_util.py
    │  util.py
    │  __init__.py
    │  __main__.py
    │
    ├─controllers
    │      authorization_controller.py
    │      default_controller.py
    │      __init__.py
    │
    ├─models
    │      base_model_.py
    │      users_body.py
    │      __init__.py
    │
    ├─swagger
    │      swagger.yaml
    │
    └─test
            test_default_controller.py
            __init__.py

FlaskAPIServer 起動

Dockerfileも生成されたので、それで起動してみる

SwaggerUIよりリクエストを送信してみたら、CORSエラーが返ってきた
CORSについてか解決できなかったので、docker-composeでSwaggerEditorとFlaskAPIServerを同時に起動。Nginxをプロキシサーバとして動かすことで、ドメインを統一してエラー回避

## ファイル構成

{Project}
|- docker-compose.yaml
|- nginx.conf
└─ swagger_server # SwaggerEditor より生成したコード

## docker-compose.yaml

version: "3.8"
services: 
    nginx:
        image: nginx
        ports: 
            - 8080:8080
        volumes:
           - ./nginx.conf:/etc/nginx/conf.d/nginx.conf
    swagger_editor:
        image: swaggerapi/swagger-editor
    flask_api_server:
        build:
            context: ./python-flask-server-generated
            dockerfile: Dockerfile

## nginx.conf

server {
    listen  8080;

    # SwaggerEfitor
    location / {
        proxy_pass http://swagger_editor:8080; 
    }

    # Flask API Server
    location ^~ /api/v1 {
        proxy_pass http://flask_api_server:8080/api/v1; 
    }
}

SwaggerUIでリクエストお試し

起動したAPIサーバに対して、SwaggerUIからリクエストを送ってみると、do some magic!とレスポンスが返ってくることを確認

SwaggerEditorを使ってみて

• API設計とドキュメント作成(Swagger UI)が同時に出来て楽
• SwaggerEditorでは、SwaggerUIがホットリロードしてくれるので書き易い
• OASで定義できる項目が多いので、前提としてAPI設計について知っておく必要がある
• 生成されたコードから編集するのみでAPIサーバを構築できるので楽

今回は以上です。