我们正在使用 rspec_api_documentation
并设法使用以下代码生成迄今为止我们拥有的 2 个版本的文档:
RspecApiDocumentation.configure do |config|
config.docs_dir = Rails.root.join('doc', 'api', 'all')
config.define_group :v1 do |config|
config.filter = :v1
config.docs_dir = Rails.root.join('doc', 'api', 'v1')
config.api_name = 'API V1'
end
config.define_group :v2 do |config|
config.filter = :v2
config.docs_dir = Rails.root.join('doc', 'api', 'v2')
config.api_name = 'API V2'
end
end
我们正在使用 apitome
来渲染这些文档,但是,到目前为止,我们还没有找到一种方法来挂载 API 2 的 2 个版本的路由。
有什么想法吗?
最佳答案
回答我自己的问题,以防对其他人有帮助。
将您的 api 版本定义为常量
API_VERSIONS = [:v1, :v2] API_LAST_VERSION = API_VERSIONS.last
为每个版本定义文档组并在单独的文件夹中输出 json 文件
# spec/spec_helper.rb RspecApiDocumentation.configure do |config| config.format = :json API_VERSIONS.each do |version| config.define_group(version) do |config| config.filter = version config.docs_dir = Rails.root.join('doc', 'api', version.to_s) end end end
在对规范进行编码时使用文档组
# spec/acceptance/v1/users_spec.rb resource 'User' do post '/users' do example 'Identify a user', document: :v1 do # your v1 spec here end end end # spec/acceptance/v2/users_spec.rb resource 'User' do post '/users' do example 'Identify a user', document: :v2 do # your v2 spec here end end end
注释掉
doc_path
和mount_at
来自config/initializers/apitome.rb
定义设置它们的路由约束
# lib/apitome_version.rb class ApitomeVersion def initialize(version) @path = "doc/api/#{ version }" end def matches?(request) # Load doc files from the right version folder Apitome.configuration.doc_path = @path # Mount all routes on the current request path (including simulated responses) Apitome.configuration.mount_at = request.path # Return a match true end end
使用该约束安装您的路由,您可以选择设置默认版本
# config/routes.rb Rails.application.routes.draw do # Mount documentation for each API version API_VERSIONS.each do |version| mount Apitome::Engine => "/api/docs/#{ version }", as: "apitome-#{ version }", constraints: ApitomeVersion.new(version) end # Optionally default to the last API version mount Apitome::Engine => '/api/docs', constraints: ApitomeVersion.new(API_LAST_VERSION) end
重新生成文档
rake docs:generate
重新启动服务器
关于使用 rspec_api_documentation 和 apitome 进行 API 版本控制,我们在Stack Overflow上找到一个类似的问题: https://stackoverflow.com/questions/33485326/