使用 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 的 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. 重新启动服务器