如何使用 Grape-Swagger 生成 API 文檔

在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 文檔了