Viron(ヴァイロン)ってご存知ですか？

2018年2月に公開されたオープンソースのWebアプリケーションで、Swaggerに対応したAPIを書くだけで管理画面とダッシュボードを構築可能です。

本当にAPIを書くだけでいいので、デザインも考えなくて良いしむしろフロント側のコードを書く必要すらなくなります。

そんなVironを半年近く使ってみたので所感をかきます。

cam-inc/viron github
viron ドキュメント

v1.3.0 を使いましたが、一部 rc について触れます。

Vironとは?

フロントレス

HTML、CSS、JavaScript等のフロント用ソースコードを記述する必要はありません。APIサーバのみを用意して下さい。

APIサーバのレスポンスからCURDとか検索とか基本的なUIは揃った綺麗な管理画面が構築されます。

ボタンを押すと指定のAPI叩くとかできるので、タスク実行とかCSVダウンロードとかUIに関係ない事はほぼできます。

vironサーバーはAPIサーバについて何も知らなくていいので、github pagesでもAWS S3の静的サイトホスティングでも良いのです。

普通のAPI作る工数からOAS準拠とかviron準拠させるために使った時間を抜き出すとそんなに時間はかかってないです。(規模とか複雑さにもよるけど3~5日くらい)

レスポンシブデザイン

デスクトップ端末とモバイル端末上で画面サイズに応じたレイアウトが設定されます。

何も書かずとも綺麗な管理画面ができるし、開発者は機能の作成だけに集中できます。

サービス毎に統一されたUIになるので利用者も嬉しい。

OAS駆動

OpenAPI Specification 2.0に準拠。

APIを記述するためのフォーマットで、Open API Initiativeによって推進されてるオープンな規格であるOpenAPI Specification 2.0に準拠。

OASに則りAPIを記述するために作成されたドキュメントは「OpenAPIドキュメント」と呼ばれ、JSON/YAMLの2つのフォーマットで記述が可能。

OpenAPI Specificationの旧名はSwagger SpecificationでSwaggerとイコールだと捉えていいと思います。

議論されたルールに乗っ取ったAPIを作れるので勉強になる。

無料/オープンソース

GitHub上でオープンソースとして公開されています。誰でも無料で使用できます。

OSSなので機能追加などのアップデートが誰かの貢献のおかげで利用できる。

issues作るなりPR投げるなりみんなで作れる。ドキュメントもOSSなのでtypo見つけたらPR投げよう。

Viron立ち上げてみる

公式のクイックスタートでHTTPS(8080) にフロント、 HTTPS(3000) にAPIサーバーが立ち上がるので気軽に試せるし、デモもあります。

今回はフロント群だけ欲しいのでdockerでビルド用コンテナ作ってビルドしました。

$ git clone -b v1.3.0 git@github.com:cam-inc/viron.git
$ docker build -t viron-builder:v1.3.0 ./viron
$ mkdir dist
$ docker run --rm -v $(pwd)/dist:/viron/_dist viron-builder:v1.3.0 /bin/bash -c "npm run build && cp -RT /viron/dist /viron/_dist"
$ docker rmi viron-builder:v1.3.0

フロント群がdistに作られたのでDockerfileを作って、公開するnginxコンテナを作ります。

FROM nginx:1.15.0
COPY ./dist /usr/share/nginx/html

$ docker build -t viron:v1.3.0 .
$ docker run --rm -p 3000:80 viron:v1.3.0

ブラウザで http://localhost:3000 を開きます。

出てきた画面からswagger.jsonを返すAPIエンドポイントを登録すると管理画面が構築されます。

APIの定義

公式ドキュメントにほぼ書いている事なのですが、必須APIが3つあり、それぞれ以下を定義します。

swaggerの取得(API定義) /swagger.json
認証方式 /viron_authtype
グローバルメニューの取得 /viron

swaggerの取得(API定義) `/swagger.json`

swaggerの作り方は以下が参考になります

定義はなかなか長くなるのでまずは全体像から見ていきます。

全体像

{
  swagger: "2.0",
  schemes: ["https"],
  host: "api.example.com",
  info: {
    version: "1.0.0",
    title: "XXX 管理",
    description: "XXX 管理 - Example Management Console"
  },
  // vironからAPIのリクエストMIMEタイプ
  //   vironからファイルをAPIで受け取りたいならmultipart/form-dataを追加します
  consumes: ["application/json"],
  // APIからvironのレスポンスMIMEタイプ
  produces: ["application/json"],
  paths: {
    //APIのエンドポイントとリクエスト方法、レスポンスについて定義
    //長いので下のセクションで説明します
  },
  definitions: {
    //レスポンスやパラメータなどを変数定義して使いまわします
    //長いので下のセクションで説明します
  }
}

paths

必須API 3種と利用したいAPIのエンドポイントとリクエスト方法、レスポンスについて定義します。

以下はuserの基本的なrest apiを定義しています。

{
  // 必須API グローバルメニューの取得
  /viron: {
    get: {
      summary: "エンドポイント全体情報取得",
      operationId: "viron#index",
      responses: {
        200: {
          description: "ok",
          schema: {
            // $refはdefinitionsセクションで定義したschemaを利用
            $ref: "#/definitions/Viron"
          }
        }
      }
    }
  }
  // 必須API 認証方式の取得
  /viron_authtype: {
    get: {
      summary: "認証方式一覧",
      operationId: "viron_authtype#index",
      responses: {
        200: {
          description: "ok",
          schema: {
            $ref: "#/definitions/VironAuthtype"
          }
        }
      }
    }
  }
  // 必須API swaggerの取得(API定義)
  /swagger.json: {
    get: {
      summary: "swagger.json取得",
      operationId: "swagger#index",
      responses: {
        200: {
          description: "ok",
            schema: {
              type: "object"
            }
          },
          500: {
            description: "Internal Server Error"
          }
        }
      }
    }
  }
  // 利用したいAPIを定義する
  /api/v1/users: {
    // 一覧画面の定義
    get: {
      x-swagger-router-controller: "users",
      summary: "ユーザー 一覧",
      description: "ユーザー 一覧",
      operationId: "users#index",
      produces: "application/json",
      tags: ["users"],
      // ?limit=1などurlでパラメータを渡したい場合は in: "query"
      // 他にもヘッダに埋め込んだり、bodyにjsonで埋め込んだり、urlに埋め込んだりできる
      parameters: [
        {
          name: "limit",
          in: "query",
          required: false,
          type: "integer"
        },
        {
          name: "offset",
          in: "query",
          required: false,
          type: "integer"
        },
        {
          name: "sort",
          in: "query",
          required: false,
          type: "string"
        },
        {
          name: "id",
          in: "query",
          required: false,
          type: "integer"
        },
        {
          name: "name",
          in: "query",
          required: false,
          type: "string"
        },
      ],
      responses: {
        200: {
          description: "ok",
          schema: {
            // $refはdefinitionsセクションで定義したschemaを利用
            // definitions/UserCollectionはUserの複数系として定義している
            $ref: "#/definitions/UserCollection"
          }
        }
      }
    }
    // 作成画面の定義
    post: {
      x-swagger-router-controller: "users",
      summary: "ユーザー 作成",
      description: "ユーザー 作成",
      operationId: "users#create",
      produces: "application/json",
      tags: ["users"],
      parameters: [
        {
          // bodyに埋め込んだユーザー情報をパラメータとして送る
          name: "payload",
          in: "body",
          required: true,
          schema: {
            // definitions/UserBuildはUserの登録パラメータ
            $ref: "#/definitions/UserBuild"
          }
        }
      ],
      responses: {
        200: {
          description: "ok",
          schema: {
            // レスポンスはid付きUserオブジェクト
            $ref: "#/definitions/User"
          }
        }
      }
    }
  },
  // ユーザーidをurlに埋め込む
  /api/v1/users/{id}: {
    // 編集画面の定義
    put: {
      x-swagger-router-controller: "users",
      summary: "ユーザー 編集",
      description: "ユーザー 編集",
      operationId: "ads#update",
      produces: "application/json",
      tags: "users",
      parameters: [
        {
          // ユーザーidパラメータがpathに埋め込まれてリクエストされる
          name: "id",
          in: "path",
          required: true,
          type: "integer"
        },
        {
          // 他のパラメータはbodyに埋め込まれてる
          name: "payload",
          in: "body",
          required: true,
          schema: {
            $ref: "#/definitions/UserBuild"
          }
        }
      ],
      responses: {
        200: {
          description: "ok",
          schema: {
            $ref: "#/definitions/User"
          }
        }
      }
    },
    // 削除ボタンの定義
    delete: {
      x-swagger-router-controller: "users",
      summary: "ユーザー 削除",
      description: "ユーザー 削除",
      operationId: "users#delete",
      produces: "application/json",
      tags: "users",
      parameters: [
        {
          name: "id",
          in: "path",
          required: true,
          type: "integer"
        }
      ],
      responses: {
        204: {
          description: "no content"
        }
      }
    }
  }
}

definitions

レスポンスやパラメータなどを変数定義して使いまわします。

$refを使って展開します $ref: "#/definitions/User"


{
  // 認証方法の取得で使ってる定義
  VironAuthtype: {
    type: "array",
      items: {
        $ref: "#/definitions/AuthType"
      }
    }
  },
  AuthType: {
    required: [
      "type",
      "url",
      "method",
      "provider"
    ],
    additionalProperties: false,
    properties: {
      type: {
        type: "string"
      },
      url: {
        type: "string"
      },
      method: {
        type: "string"
      },
      provider: {
        type: "string"
      }
    }
  },
  // すでに登録されている単数モデル
  User: {
    type: "object",
    required: ["name"],
    additionalProperties: false,
    properties: {
      id: {
        type: "integer",
        description: "ID",
        example: 1
      },
      name: {
        type: "string",
        description: "名前",
        example: "山田"
      }
    }
  },
  // 登録する前の単数モデル
  UserBuild: {
    type: "object",
    required: ["name"],
    additionalProperties: false,
    properties: {
      name: {
        type: "string",
        description: "名前",
        example: "山田"
      }
    }
  },
  // #indexで返すモデルのリスト
  UserCollection: {
    type: "array",
    items: {
      $ref: "#/definitions/User"
    }
  }
}

認証方式 `/viron_authtype`

認証方式

独自にメールアドレスとパスワードを保存したユーザーテーブル作るとか、Googleログインとか利用できる。


[
  // メールアドレスとパスワードによる認証。利用しない場合は削除しても良い
  {
    type: 'email', // メールアドレスとパスワードによる独自認証を利用する場合のtype
    provider: 'viron-example',
    url: '/signin', // サインインフォームでsubmitする際のリクエストURL
    method: 'POST', // submitする際のリクエストメソッド
  },
  // GoogleOAuthによる認証。利用しない場合は削除しても良い
  {
    type: 'oauth', // OAuth認証を利用する場合のtype
    provider: 'google', // OAuthを提供するプロバイダ。
    url: '/googlesignin',
    method: 'POST',
  },
  // 認証方式ではありませんが、サインアウト時にコールするAPIを定義するために必須です。
  {
    type: 'signout',
    provider: '',
    url: '/signout',
    method: 'POST',
  },
];

グローバルメニューの取得 `/viron`

グローバルメニューの取得

ほぼほぼ日本語で説明されてるけど一部説明付け足しました。


{
  // エンドポイントに関する情報
  "theme": "standard", // カラーテーマ
  "color": "white", // ドットカラー
  "name": "Viron example - local", // エンドポイントの名称。サービス名や環境など
  "tags": [ // エンドポイントに付与するタグ
    "local",
    "viron",
    "example"
  ],
  "thumbnail": "https://avatars3.githubusercontent.com/u/23251378?v=3&s=200", // サムネイル画像URL
  // グローバルメニュー定義
  "pages": [
    {
      "section": "dashboard" // 大項目。"dashboard" or "manage"
      "group": "", // 中項目。空の場合はsection直下にcomponentsを配置
      "id": "quickview", // ページのID。全ページでユニークになっている必要があります
      "name": "クイックビュー", // ページ名
      "components": [ // メニューからページを選択した際に表示されるコンポーネントの一覧
        {
          "api": { // コンポーネントに表示する値を取得するためのAPI
            "method": "get",
            "path": "/stats/dau"
          },
          "name": "DAU", // コンポーネント名
          "style": "number" // コンポーネントスタイル。数字(number)、テーブル(table)の他に各種グラフ(graph-*)が利用できます
        },
        {
          "api": {
            "method": "get",
            "path": "/users"
          },
          "name": "MAU",
          "style": "table",
          // ヘッダに値を入れることでページングを可能にする(X-Pagination-Limitなど、後述します)
          "pagination": true,
          // 検索パラメータとして送れる値を定義
          "query": [
            {
              key: "id",
              type: "integer"
            },
            {
              key: "name",
              type: "string",
            }
            {
              // 文字列でリクエストするけど、フォームを日付形式にする
              key: "created_at",
              type: "string",
              format: "date-time"
            },
          ],
          // ソート可能にする v1.4.0でリリース予定? 現状rcブランチで使えます
          // APIにはsortパラメータにコロンとカンマで区切った形式で渡される('id:asc,name:desc')
          sort: [
            "id",
            "name"
          ],
        },
      ],
    },
    {
      "section": "manage"
      "group": "user",
      "id": "user",
      "name": "ユーザー",
      "components": [
        {
          "api": {
            "method": "get",
            "path": "/user"
          },
          "name": "ユーザー",
          "style": "table",
          "primary": "id", // テーブルデータの主キーにあたるフィールド
          "pagination": true, // テーブルスタイルのページャーを有効にするフラグ
          "query": [ // テーブルスタイルの検索フィールドを指定
            {
              "key": "name",
              "type": "string"
            }
          ],
          "table_labels": [ // テーブルスタイルの見出しにするフィールドを指定
            "id",
            "name"
          ],
          "actions": [ // 他APIの関連付けが必要な場合は指定。詳細は下記[API間の関連付け]を参照
            "/user/download/csv"
          ]
        }
      ],
    },
  ],
}

ruby on railsでAPI実装する

ruby on railsでAPI実装する場合のだいたいの流れを書きます。

ルーティング

必須API3つと管理画面構築に必要なAPIをルーティングします。

# config/routes.rb
Rails.application.routes.draw do

  resource :viron, only: %i[show], format: false
  resource :viron_authtype, only: %i[show], format: false
  resource :swagger, only: %i[show], constraints: lambda { |req| req.format == :json }

  namespace :api, defaults: { format: :json } do
    namespace :v1 do
      resources :users
    end
  end
end

cors設定

CORS(Cross-Origin Resource Sharing)するための設定を書く必要があります。

Webサイトが持つ情報が別の悪意あるWebサイトに悪用されるのを防ぐために、Same-Origin Policy(日本語では同一生成元ポリシー)が適用されます。

クライアント(ブラウザ)から見知らぬドメイン当てにリクエストを行うことになるのでブラウザがブロックする(親切)ので事前に許可する必要がある。

gem rack-corsがよしなに Access-Control-Allow-xxx や Access-Control-Expose-xxx ヘッダをつけてくれます。

# Gemfile
gem 'rack-cors'

# config/initializers/cors.rb
Rails.application.config.middleware.insert_before 0, Rack::Cors do
  allow do
    origins ['viron.example.com'] # 許可するhost
    resource '/api/*', headers: :any, methods: [:get, :post, :delete, :put, :options], expose: [
      'Origin', 'Content-Type', 'Content-Disposition', 'Accept', 'Authorization',
      'X-Requested-With', 'X-Authorization',
      'X-Pagination-Limit', 'X-Pagination-Total-Pages', 'X-Pagination-Current-Page',
    ]
    resource '/viron', headers: :any, methods: [:get]
    resource '/viron_authtype', headers: :any, methods: [:get]
    resource '/swagger.json', headers: :any, methods: [:get]
  end
end

swagger定義

swagger-docsというgemはルーティング(やたぶんモデル)を見て動的にswagger定義を書いてくれる!!!のですが、

I don't currently have any plans to add support for v2.0 at this time due to time constraints

v2.0のサポートを追加する予定はありませんとのことなのである程度楽にかける swagger-blocks を利用しました。

gem 'swagger-blocks'

あとは以下を参考に定義をもくもくと書いていきます。

管理画面は設定ファイルぐらいシンプルに作れるべき！『Viron』を使ってみました

github RailsでViron対応管理画面を作る

ページネーション対応

グローバルメニューの取得(/viron)でページネーションを有効にしていて、ページ総数や現在のページ数などを指定ヘッダにいれてレスポンスを返すとページネーションしてくれます。

response.headers['X-Pagination-Limit'] = @limit
response.headers['X-Pagination-Total-Pages'] = (@users.unscope(:limit).unscope(:offset).count / @limit.to_f).ceil
response.headers['X-Pagination-Current-Page'] = @offset / @limit + 1

ソート

v1.4.0でリリース予定?、rcブランチで使える機能ですが、

グローバルメニューの取得(/viron)でソートする列を指定していればソート可能になります。

リクエストに id:asc,name:desc のような形式で送られてくるのでよしなに処理します。

def parse_order query
  query
    .split(',')
    .map{|v| v.split(':') }
    .select{|v| v.size === 2 && v[0].present? && v[1].present? && ['desc', 'asc'].include?(v[1]) }
    .map{|v| [v[0], v[1]] }
    .to_h
end

params[:sort]
=> 'id:asc,name:desc'

order_params = parse_order(params[:sort])
=> {"id"=>"asc", "name"=>"desc"}

users.order!(parse_order(params[:sort])) if params[:sort].present?

controller

だいたいこんな感じになりました。

# 雰囲気users_controller.rb
class Api::V1::UsersController < ApplicationController
  before_action :set_limit_offset, only: [:index]
  before_action :set_users, only: [:index]
  before_action :set_user, only: [:create, :show, :update, :destroy]
  before_action :set_pagination_headers, only: [:index]

  def index
    render json: @users
  end

  def show
    render json: @user
  end

  def create
    if @user.save
      render json: @user, status: :created
    else
      render json: @user.errors, status: :unprocessable_entity
    end
  end

  def update
    if @user.update(update_params)
      render json: @user
    else
      render json: @user.errors, status: :unprocessable_entity
    end
  end

  def destroy
    @user.destroy
  end

  private
    def set_limit_offset
      @limit = params[:limit]&.to_i || 100
      @offset = params[:offset]&.to_i || 0
    end

    def set_users
      @users = User.all.limit(@limit).offset(@offset)
      @users.order!(parse_order(params[:sort])) if params[:sort].present?
      @users.where!(search_params) if search_params.present?
    end

    def set_pagination_headers
      response.headers['X-Pagination-Limit'] = @limit
      response.headers['X-Pagination-Total-Pages'] = (@users.unscope(:limit).unscope(:offset).count / @limit.to_f).ceil
      response.headers['X-Pagination-Current-Page'] = @offset / @limit + 1
    end

    def search_params
      params.permit(:id, :name)
        .select {|key, value| value.present? }
    end

    def update_params
      params.require(:user).permit(:name)
    end
end

所感

いいところ

表のみならずグラフ表示やダッシュボードもあるのでBIツールにもなり得そうです。

API書くだけでいいので、ユースケースに合えば(ドラッグしたりUIゴリゴリじゃなければ)かなりの速度で開発出来ます。

actionを定義出来る(パラメータ指定してCRUD以外にもAPI叩ける)のでCSVダウンロードしたりバッチ起動したりとか柔軟に機能を追加出来ます。

swaggerはもともとAPI仕様を作ったり、テストも出来る便利な規格でしたが、Vironで管理画面も自動構築出来てしまうので1石3鳥です。

とはいえ

日付の入力フォームが(todayやnowなど補完はしてくれるが)文字列なので厳しいです。これに関しては DatePicker UI Component #269 で進んでいるようなので今後に期待します。

ソートはまだ正式リリースされていないです。次のバージョンでリリースされるのかな。Table filter #341

オートコンプリートに関しては、補完はしてくれるのですが、表示する値(名前など)とパラメータにする値(IDなど)を分ける事が出来ず、これも今後に期待です。

1レコードの編集に2click以上(歯車押して編集押す or レコード押して表示して編集押す)なのも地味にきます。

ほんとに書かなくなるのでたまにjs書きたくなる。

さいごに

ユースケース確認して要件合えば今後も使いたいと思います。

導入に時間はかからないので試してみてはどうでしょうか？

Vironを半年近く使ってみた