如何使用 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这里有两点说明：
-
grape-swagger指定了版本号，0.10.2是当前最新版本， 因为老的版本0.10.1会存在hide_format参数无法正常工作的问题，这个问题在最新版本中修复了。 -
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 文档了
正文到此结束
热门推荐
相关文章
近期评论
-
666
-
文章和留言都翻到11页了 没有OOM
-
-
朋友，翻页到11页，及以后，会出现OOM，无法访问
-
-
-
-
版本号是多少，你可以下载哪个代码仓库，jdk选1.8 直接跑就行
-
-
Loading...
![[HBLOG]公众号](https://www.liuhaihua.cn/img/qrcode_gzh.jpg)
