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



分享给朋友:
您可能感兴趣的文章:
随机阅读: