SwaggerYard

SwaggerYard is a gem to convert extended YARD syntax comments into the swagger spec compliant json format.

Installation

Put SwaggerYard in your Gemfile:

gem 'swagger_yard'

Install the gem with Bunder:

bundle install

Getting Started

Place your configuration in a your rails initializers

# config/initializers/swagger_yard.rb
SwaggerYard.configure do |config|
  config.swagger_version = "1.2"
  config.api_version = "1.0"
  config.reload = Rails.env.development?

  # where your swagger spec json will show up
  config.swagger_spec_base_path = "http://localhost:3000/swagger/api"
  # where your actual api is hosted from
  config.api_base_path = "http://localhost:3000/api"
end

# register swagger tags with YARD
SwaggerYard.register_custom_yard_tags!

Example Documentation

Here is an example of how to use SwaggerYard in your Controller

Note: Model references should be Capitalized or CamelCased, basic types (integer, boolean, string, etc) should be lowercased everywhere.

# @resource Account ownership
#
# @resource_path /accounts/ownerships
#
# This document describes the API for creating, reading, and deleting account ownerships.
#
class Accounts::OwnershipsController < ActionController::Base
  ##
  # Returns a list of ownerships associated with the account.
  #
  # @notes Status can be -1(Deleted), 0(Inactive), 1(Active), 2(Expired) and 3(Cancelled).
  #
  # @path [GET] /accounts/ownerships.{format_type}
  #
  # @parameter offset   [integer]               Used for pagination of response data (default: 25 items per response). Specifies the offset of the next block of data to receive.
  # @parameter status   [array<string>]                 Filter by status. (e.g. status[]=1&status[]=2&status[]=3).
  # @parameter_list     [String]    sort_order        Orders response by fields. (e.g. sort_order=created_at).
  #                     [List]      id
  #                     [List]      begin_at
  #                     [List]      end_at
  #                     [List]      created_at
  # @parameter sort_descending    [boolean]     Reverse order of sort_order sorting, make it descending.
  # @parameter begin_at_greater   [date]        Filters response to include only items with begin_at >= specified timestamp (e.g. begin_at_greater=2012-02-15T02:06:56Z).
  # @parameter begin_at_less      [date]        Filters response to include only items with begin_at <= specified timestamp (e.g. begin_at_less=2012-02-15T02:06:56Z).
  # @parameter end_at_greater     [date]        Filters response to include only items with end_at >= specified timestamp (e.g. end_at_greater=2012-02-15T02:06:56Z).
  # @parameter end_at_less        [date]        Filters response to include only items with end_at <= specified timestamp (e.g. end_at_less=2012-02-15T02:06:56Z).
  #
  def index
    ...
  end

  ##
  # Returns an ownership for an account by id
  # 
  # @path [GET] /accounts/ownerships/{id}.{format_type}
  # @response_type [Ownership]
  # @error_message [EmptyOwnership] 404 Ownership not found
  # @error_message 400 Invalid ID supplied
  #
  def show
    ...
  end
end

Here is an example of how to use SwaggerYard in your Model

#
# @model Pet
#
# @property id(required)    [integer]   the identifier for the pet
# @property name  [Array<string>]    the names for the pet
# @property age   [integer]   the age of the pet
# @property relatives(required) [Array<Pet>] other Pets in its family
#
class Pet
end

To then use your Model in your Controller documentation, add @parameters:

# @parameter [Pet] pet The pet object

Authorization

Currently, SwaggerYard only supports API Key auth descriptions. Start by adding @authorization to your ApplicationController.

#
# @authorization [api_key] header X-APPLICATION-API-KEY
#
class ApplicationController < ActionController::Base
end

Then you can use these authorizations from your controller or actions in a controller. The name comes from either header or query plus the name of the key downcased/underscored.

#
# @authorize_with header_x_application_api_key
#
class PetController < ApplicationController
end

UI

It is advisable to use something like swagger-ui_rails for your UI needs inside of Rails.