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
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
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
...
# A list of all classes that have swagger_* declarations.
SWAGGERED_CLASSES = [
...
Swagger::Requests::Profile,
Swagger::Schemas::Email,
...
].freeze
...
Help and feedback
Get help from the Platform Support Team in Slack.
Submit a feature idea to the Platform.