在Rails 專案中使用 Grape 來開發 API, 想嘗試一下通過 swagger 來自動生成 API 文件，至於為什麼要選 swagger 也沒有特別的理由, 在 Ruby China 看過幾篇分享。然後開始 Google 官方文件和一些列子，中間也碰到一些坑，此文主要是總結下配置 swagger 的過程。

安裝相關的 Gem

在 Gemfile 中新增 grape-swagger 和 grape-swagger-rails 這兩個 gem。

source 'https://rubygems.org'

gem 'rails', '4.2.3'
gem 'sqlite3'
gem 'sass-rails'
 
, '~> 5.0'
gem 'uglifier', '>= 1.3.0'
gem 'coffee-rails', '~> 4.1.0'

gem 'jquery-rails'
gem 'turbolinks'
gem 'jbuilder', '~> 2.0'

gem 'grape'
gem 'grape-swagger', '~> 0.10.2'
gem 'grape-swagger-rails', '~> 0.1.0'

group :development, :test do
  gem 'byebug'

  gem 'web-console', '~> 2.0'
 

  gem 'spring'
end

這裡有兩點說明：

1. grape-swagger 指定了版本號，0.10.2 是當前最新版本， 因為老的版本 0.10.1 會存在 hide_format 引數無法正常工作的問題，這個問題在最新版本中修復了。

2. grape-swagger-rails 是 Swagger UI 的 Rails Engine , 也是必備的元件。

配置 swagger

看 grape-swagger 的官方文件的用法介紹，主要是新增兩行程式碼 require-swagger 和 add_swagger_documentation.

• require-swagger 當然就是 引入 grape-swagger 這個 gem 了

• add_swagger_documentation 是在這裡開始生成文件的 method

假設，當前我的 API 的 目錄結果是這樣的：

.
├── application_api.rb
└── v1
    ├── base_api.rb
    └── post_api.rb

application.rb:

require "grape-swagger"
class ApplicationAPI < Grape::API
  content_type :json, 'application/json;charset=UTF-8'
  format :json
  
  mount V1::Base
end

base.rb:

module V1
  class Base < Grape::API
    version 'v1', using: :path
    mount V1::PostApi
    add_swagger_documentation(
      :api_version => "api/v1",
      hide_documentation_path: true,
      hide_format: true
    )
  end
end

application_api.rb 是最底層的，裡面放最通用的配置，所以在這裡 require 'grape-swagger'，這樣不用每次都 require 了. 當前 API 的版本是 V1, v1\base.rb 會 mount 所有的 API, 所以我們在 v1/base_api.rb 中新增 add_swagger_documentation。

三個常用的引數：

• api_version: 需要設定正確，如果設定錯誤會無法正確生成文件

• hide_cocumentation_path: 隱藏文件路徑

• hide_format: 這個是去除 URL 後面的格式字尾： (.json), 這樣便於我們在網頁面直接測試 API

配置 Swagger UI

接下來目標要使 grape-swagger-rails 正常工作。

• 在config/initializers 目錄下新增 swagger-rails.rb 檔案

GrapeSwaggerRails.options.url      = "/api/v1/swagger_doc"
GrapeSwaggerRails.options.app_url  = '/'

• 在 config/routes.rb 檔案中指明 apidoc 的路徑

Rails.application.routes.draw do
  mount ApplicationAPI => '/api'
  mount GrapeSwaggerRails::Engine => '/apidoc'
end

現在就可以通過 http://localhost:3000/apidoc 訪問 API 文件了