如何使用 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 文档了