This API is to be used within the Referral System and by Apex Systems MDC
Swagger UI is available at: /api-docs
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
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 |
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
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" |
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
-
...