swagger + grape + rack

2017.01.24

ruby

常常聽到 swagger 跟 grape 的名字

所以用一個很陽春的專案練習一下要如何使用

使用到的 Gem: ¶

grape API 框架
grape-swagger API 文件產生器
vienna 簡單設定讓 Rack 處理public 靜態文件

其他使用到的 Repo ¶

swagger-ui API 文件瀏覽前端

開發 ¶

用 grape 開發 API，以及加上 swagger 文件支援，這些都照著官方文件走就可以了

由於要用 rack 同時跑 API 與 swagger-ui，所以在 config.ru 用了 vienna

vienna 可以讓 rack 套用 public 目錄下的靜態檔案成為網站的一部份

config.ru 範例

require 'bundler/setup'
Bundler.require

require "vienna"
require "grape"
require "grape-swagger"
require_relative "twitter/api.rb"

module API
  class Root < Grape::API
    format :json

    # CORS
    before do
      header['Access-Control-Allow-Origin'] = '*'
      header['Access-Control-Request-Method'] = '*'
    end

    mount Twitter::API
    add_swagger_documentation
  end
end

# 除了 API 還要跑 public 下的靜態檔案
run Rack::Cascade.new [API::Root, Vienna]

Swagger UI ¶

從 swagger-ui 下載壓縮檔

把 swagger-ui/dist 下的檔案複製到專案的 public 目錄下

打開 index.html 將

if (url && url.length > 1) {
  url = decodeURIComponent(url[1]);
} else {
  url = "http://petstore.swagger.io/v2/swagger.json";
}

修改成

if (url && url.length > 1) {
  url = decodeURIComponent(url[1]);
} else {
  url = "http://localhost:9292/swagger_doc.json";
}

Execute ¶

Run command:

bundle exec rackup

打開瀏覽器瀏覽 http://localhost:9292/ 就可以看到 swagger 風格的 API 文件了！

Bear Su's Blog