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

从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版本控制

1 个答案: