Swagger Implementation

Introduction

Creating a service backend endpoint for http://va.gov is a common task for developers. Due to the complexity of integrating with legacy VA REST or SOAP applications we've developed a pattern for making these connections. This document details an example of the swagger declaration for Vets API.

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

CODE

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

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

CODE

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

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

CODE

...

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

...

Help and feedback

Suggest content changes to this page.
Submit new Platform Website content.
Get help from the Platform Support Team in Slack.
Submit a feature idea to the Platform.