如何使用 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::Baseend

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    )  endend

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 文档了