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

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

回答我自己的问题以防对其他人有帮助。

将您的 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

从config/initializers/apitome.rb

doc_path

mount_at

定义设置它们的路由约束

# 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
```
重新启动服务器

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

API versioning with rspec_api_documentation and apitome

versioning

api

rspec

rspec-api-documentation