Take the documentation out of the controller

[boyfunky]

I am trying to take my documentation out of my controller not sure if this possible and how to do it.

so sample Controller has this

class VI::SomeController < ActionController::API
   include Swagger::Blocks
 end

in my Apidocs controller this is the definition

class ApidocsController < ActionController::API

  include Swagger::Blocks

  swagger_root do
    key :swagger, '2.0'
    info do
      key :version, '1.0.0'
      key :title, 'Loanplus API'
      key :description, 'Loanplus API Specification'
    end
    # tag do
    #   key :name, 'mortgage_loans'
    #   key :description, 'Get mortgage loans'
    # end

    key :host, HOST
    key :basePath, '/api/v1'
    key :consumes, ['application/json']
    key :produces, ['application/json']

    # security_definition :api_key do
    #   key :type, :apiKey
    #   key :name, :api_key
    #   key :in, :query
    # end
    #
    # security do
    #   key :api_key, []
    # end
  end

  # A list of all classes that have swagger_* declarations.
  SWAGGERED_CLASSES = [V1::LpDeveloperReferralsController, self].freeze

  def index
    result = Swagger::Blocks.build_root_json(SWAGGERED_CLASSES)
    render json: result
  end
end

How can i put the documentation somewhere else. I tried putting the documentation to a concern and calling it from there but doesnt work. Any other options

[davingee]

👍

[john-goldsmith]

@boyfunky It might not be the best or most Rails-y way of doing it, but here's how I accomplished moving the Swagger documentation out of the controllers in my project. Basically every controller/model has a corresponding concern that gets included.

# app/controllers/v1/some_controller.rb -- a generic controller
module V1
  class SomeController < ActionController::API
    include V1::Concerns::Docs::SomeController
    # controller actions, etc.
  end
end

# app/controllers/v1/concerns/docs/some_controller.rb -- documentation for a specific controller
module V1
  module Concerns
    module Docs
      extend ActiveSupport::Concern
      included do
        include Swagger::Blocks
        swagger_path "/something" do
          # etc.
        end
      end
    end
  end
end

# app/controllers/v1/docs_controller.rb -- the controller that will serve the docs
module V1
  class DocsController < ActionController::API
    include V1::Concerns::Docs::DocsController
  end
end

# app/controllers/v1/concerns/docs/docs_controller.rb -- the root documentation and action
module V1
  module Concerns
    module Docs
      extend ActiveSupport::Concern
      included do
        include Swagger::Blocks
        swagger_root do
          # etc.
        end

        SWAGGERED_CLASSES = [
          V1::SomeController,
          self
        ].freeze

        def index
          result = Swagger::Blocks.build_root_json(SWAGGERED_CLASSES)
          render json: result
        end
      end
    end
  end
end

The same pattern can be applied to documenting models. Hope it helps and let me know how it can be improved!

[alecarneiro1993]

2 years since the last response, but maybe I can give my updates on this.

After trying it out for sometime, you can actually put in in a module and import to the class you want, just like the concern example above.

So you could have something like:

module Docs
  module Controllers
     module MyController
        def self.included(base)
          base.class_eval do
             include Swagger::Blocks
              # your swagger block code
          end
        end
     end
  end
end

And import it in the respective controller/model/whatever file.

include ::Docs::Controllers::MyController

And put the controller in the SWAGGERED_CLASSES

 SWAGGERED_CLASSES = [
          MyController,
          self
].freeze

So basically, this allows you to have your own namespace for your documentation inside your project, instead of putting the swagger block code inside the file or concerns.