1-app-swagger-requests-profile.rb

# vets-api/app/swagger/requests/profile.rb

module Swagger
  module Requests
    class Profile
      include Swagger::Blocks

      swagger_path '/v0/profile/email' do
        operation :get do
          extend Swagger::Responses::AuthenticationError

          key :description, 'Gets a users email address information'
          key :operationId, 'getEmailAddress'
          key :tags, %w[
            profile
          ]

          parameter :authorization

          response 200 do
            key :description, 'Response is OK'
            schema do
              key :'$ref', :Email
            end
          end
        end
      end
    end
  end
end

2-app-swagger-schemas-email.rb

# vets-api/app/swagger/schemas/email.rb

module Swagger
  module Schemas
    class Email
      include Swagger::Blocks

      swagger_schema :Email do
        key :required, [:data]

        property :data, type: :object do
          key :required, [:attributes]
          property :attributes, type: :object do
            property :email, type: :string, example: 'john@example.com'
            property :effective_at, type: :string, example: '2018-02-27T14:41:32.283Z'
          end
        end
      end
    end
  end
end

3-controllers-v0-apidocs_controller.rb

# vets-api/app/controllers/v0/apidocs_controller.rb

...

# A list of all classes that have swagger_* declarations.
SWAGGERED_CLASSES = [
  ...
  Swagger::Requests::Profile,
  Swagger::Schemas::Email,
  ...
].freeze

...