Referral System API

This API is to be used within the Referral System and by Apex Systems MDC

Swagger

Swagger UI is available at: /api-docs

Example usage

Documenting a controller:

swagger_controller :users, "User Management"

swagger_api :index do
  summary "Fetches all User items"
  notes "This lists all the active users"
  param :query, :page, :integer, :optional, "Page number"
  response :unauthorized
  response :not_acceptable
  response :requested_range_not_satisfiable
end

Swagger Controller

This syntax must be just right after the definition of you Class

class WelcomeController < ApplicationController
  swagger_controller :users, "User Management"
end

Option	Description	Required	Example
Name	This is the identifier for your controller	Yes	:users
Description	This is the description for your controller	Yes	User Management
Resource Path	This is when your controller has a custom path	No	/some/where

Swagger API

This syntax must be before the method/action definition

class WelcomeController < ApplicationController
  swagger_controller :users, "User Management"

  swagger_api :index do
    summary "Fetches all User items"
    notes "This lists all the active users"
    param :query, :page, :integer, :optional, "Page number"
    param :path, :id, :integer, :optional, "User ID"
    param :body, :body, :string, :required, "Body Param"
    param :form, :last_name, :string, :required, "Form Param"
    param_list :form, :role, :string, :required, "Param List", [ "admin", "superadmin", "user" ]
    param :header, 'Content-Type', :string, :required, "Content Type"
    response :unauthorized
    response :not_acceptable
    response :bad_request, "This is a bad request"
    response :requested_range_not_satisfiable
    response :ok, "Success"
  end
  def index
    # index action
  end
end

DSL Methods

Method	Description	Param 1	Param 2	Param 3	Param 4	Param 5	Example
Summary	The summary of this API endpoint.	:string summary	N/A	N/A	N/A	N/A	summary "Fetches all User items"
Notes	The associated notes for the API.	:string notes	N/A	N/A	N/A	N/A	notes "This lists all the active users"
Param	Standard API Parameter.	:query, :path, :body, :form, :header	:name	:string, :integer variable type	:optional, :required	:string description	param :path, :id, :integer, :optional, "User ID"
Param List	Standard API Enum/List parameter.	:query, :path, :body, :form, :header	:name	:string, :integer variable type	:optional, :required	:string description, [options]	param_list :form, :role, :string, :required, "Param List", [ "admin", "superadmin", "user" ]
Response	Takes a symbol or status code and passes it to `Rack::Utils.status_code`. The current list of status codes can be seen here: https://github.com/rack/rack/blob/master/lib/rack/utils.rb. An optional message can be added.	:symbol response	:string description	N/A	N/A	N/A	response :bad_request, "This is a bad request"

For additional details please check: *[https://github.com/richhollis/swagger-docs](https://github.com/richhollis/swagger-docs/blob/master/README.md)*

TBD

Things you may want to cover:

• Ruby version

• System dependencies

• Configuration

• Database creation

• Database initialization

• How to run the test suite

• Services (job queues, cache servers, search engines, etc.)

• Deployment instructions

• ...