使用rspec_api_documentation和apitome进行API版本控制

Question

我们正在使用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安装路由的方法.

有任何想法吗？

Answer 1

回答我自己的问题,以防它帮助别人.

1. 将api版本定义为常量

   API_VERSIONS = [:v1, :v2]
   API_LAST_VERSION = API_VERSIONS.last
   

2. 为每个版本定义文档组,并在单独的文件夹上输出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
   

3. 在编写规范时使用文档组

   # 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
   

4. 注释掉doc_path并mount_at从config/initializers/apitome.rb

5. 定义设置它们的路径约束

   # 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
   

6. 使用该约束装载路线,您可以选择设置默认版本

   # 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
   

7. 重新生成您的文档

   rake docs:generate
   

8. 重启服务器