We are using rspec_api_documentation
and managed to generate the documentation for the 2 versions we have so far with the following code:
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
We are using apitome
to render these docs, however, we haven't been able to find a way to mount the routes for the 2 versions of the API 2 so far.
Any ideas?
Answering my own question in case it helps others.
Define your api versions as constants
API_VERSIONS = [:v1, :v2]
API_LAST_VERSION = API_VERSIONS.last
Define document groups for each version and output json files on separate folders
# 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
Use the document groups when coding your specs
# 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
Comment out doc_path
and mount_at
from config/initializers/apitome.rb
Define a route constraint which sets them
# 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
Mount your routes using that constraint, you can optionally set a default version
# 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
Regenerate your documentation
rake docs:generate
Restart your server
If you love us? You can donate to us via Paypal or buy me a coffee so we can maintain and grow! Thank you!
Donate Us With