Commit 4bdbc6ad authored by Samir Noir's avatar Samir Noir 🧀
Browse files

Add reference and status API documentation, using Swagger

parent 3f4959e2
......@@ -24,6 +24,8 @@ gem 'erubis', '~> 2.7'
gem 'sass-rails'
gem 'uglifier'
gem 'swagger-blocks', '~> 3.0'
group :development do
# for ruby scripts written to replicate
# bugs
......
......@@ -252,6 +252,7 @@ GEM
state_machines-activerecord (0.6.0)
activerecord (>= 4.1)
state_machines-activemodel (>= 0.5.0)
swagger-blocks (3.0.0)
syslogger (1.6.5)
temple (0.8.2)
thin (1.7.2)
......@@ -310,6 +311,7 @@ DEPENDENCIES
sass-rails
simplecov
state_machines-activerecord
swagger-blocks (~> 3.0)
syslogger
thin (~> 1.7.0)
uglifier
......
class ApidocsController < ActionController::Base
include Swagger::Blocks
swagger_root do
key :openapi, '3.0.0'
info do
key :version, '3.0'
key :title, "Grid'5000 API"
key :description, "Grid'5000 complete API"
contact do
key :name, 'support-staff@lists.grid5000.fr'
end
license do
key :name, 'Apache 2.0'
end
end
tag do
key :name, 'reference-api'
key :description, "Reference-api expose Grid'5000's reference-repository, "\
"the single source of truth about sites, clusters, nodes, and network topology."
end
tag do
key :name, 'status'
key :description, "Status API allows tu known the state of OAR's resources "\
"(like nodes, disks, vlans, subnets). The current and upcoming "\
"reservations are also returned by this API."
end
server do
key :url, 'https://api.grid5000.fr/3.0'
end
end
swagger_component do
parameter :deep do
key :name, :deep
key :in, :query
key :description, 'Fetch a full view of reference-repository, under this path.'
key :required, false
key :type, :bool
end
parameter :version do
key :name, :version
key :in, :query
key :description, "Specificy the reference-repository's commit hash to get. " \
"This allow to get a specific version of the requested resource, to go back "\
"in time."
key :required, false
key :type, :string
end
parameter :timestamp do
key :name, :timestamp
key :in, :query
key :description, 'Fetch the version of reference-repository for the ' \
'specified UNIX timestamp.'
key :required, false
key :type, :integer
end
parameter :date do
key :name, :date
key :in, :query
key :description, 'Fetch the version of reference-repository for the ' \
'specified date (ISO_8601 format).'
key :required, false
key :type, :string
key :format, :'date-time'
end
parameter :branch do
key :name, :branch
key :in, :query
key :description, "Use a specific branch of reference-repository, for example "\
"the 'testing' branch contains the resources that are not yet in production."
key :required, false
key :type, :string
key :default, 'master'
end
parameter :clusterId do
key :name, :clusterId
key :in, :path
key :description, 'ID of cluster to fetch.'
key :required, true
key :type, :string
end
parameter :siteId do
key :name, :siteId
key :in, :path
key :description, 'ID of site to fetch.'
key :required, true
key :type, :string
end
parameter :nodeId do
key :name, :nodeId
key :in, :path
key :description, 'ID of node to fetch.'
key :required, true
key :type, :string
end
parameter :pduId do
key :name, :pduId
key :in, :path
key :description, 'ID of pdu to fetch.'
key :required, true
key :type, :string
end
parameter :serverId do
key :name, :serverId
key :in, :path
key :description, 'ID of server to fetch.'
key :required, true
key :type, :string
end
parameter :networkEquipmentId do
key :name, :networkEquipmentId
key :in, :path
key :description, 'ID of network equipment to fetch.'
key :required, true
key :type, :string
end
parameter :statusDisks do
key :name, :disks
key :in, :query
key :description, "Enable or disable status of disks in response. "\
"Should be 'yes' or 'no'."
key :required, false
key :type, :string
key :pattern, '^(no|yes)$'
key :default, 'yes'
end
parameter :statusNodes do
key :name, :nodes
key :in, :query
key :description, "Enable or disable status of nodes in response. "\
"Should be 'yes' or 'no'."
key :required, false
key :type, :string
key :pattern, '^(no|yes)$'
key :default, 'yes'
end
parameter :statusVlans do
key :name, :vlans
key :in, :query
key :description, "Enable or disable status of vlans in response. "\
"Should be 'yes' or 'no'."
key :required, false
key :type, :string
key :pattern, '^(no|yes)$'
key :default, 'yes'
end
parameter :statusSubnets do
key :name, :subnets
key :in, :query
key :description, "Enable or disable status of subnets in response. "\
"Should be 'yes' or 'no'."
key :required, false
key :type, :string
key :pattern, '^(no|yes)$'
key :default, 'yes'
end
end
# A list of all classes that have swagger_* declarations.
SWAGGERED_CLASSES = [
SitesController,
ClustersController,
ResourcesController,
self
].freeze
def index
render json: Swagger::Blocks.build_root_json(SWAGGERED_CLASSES)
end
end
......@@ -12,6 +12,8 @@
# See the License for the specific language governing permissions and
# limitations under the License.
require 'swagger'
class ApplicationController < ActionController::Base
include ApplicationHelper
......
......@@ -20,6 +20,33 @@ require 'resources_controller'
# the ClustersController is a special case of a SitesController,
# for specific clusters, insofar that this attribute is limited to the status function
class ClustersController < ResourcesController
include Swagger::Blocks
swagger_path '/sites/{siteId}/clusters/{clusterId}/status' do
operation :get do
key :summary, 'Get cluster status'
key :description, 'Fetch cluster OAR resources status and reservations.'
key :tags, ['status']
parameter do
key :$ref, :clusterId
end
parameter do
key :$ref, :statusDisks
end
parameter do
key :$ref, :statusNodes
end
response 200 do
key :description, "Grid'5000 cluster's OAR resources status."
content :'application/json'
end
end
end
# method to return status of a specific cluster - bug 5856
def status
result = {
......
......@@ -15,6 +15,75 @@
require 'resources_controller'
class NodesController < ResourcesController
include Swagger::Blocks
swagger_path '/sites/{siteId}/clusters/{clusterId}/nodes' do
operation :get do
key :summary, 'List nodes'
key :description, "Fetch a collection of Grid'5000 nodes, of a specific cluster."
key :tags, ['reference-api']
parameter do
key :$ref, :deep
end
parameter do
key :$ref, :siteId
end
parameter do
key :$ref, :clusterId
end
parameter do
key :$ref, :branch
end
response 200 do
key :description, "Grid'5000 nodes collection."
content :'application/json'
end
end
end
swagger_path '/sites/{siteId}/clusters/{clusterId}/nodes/{nodeId}' do
operation :get do
key :summary, 'Get node description'
key :description, 'Fetch the description of a specific node.'
key :tags, ['reference-api']
parameter do
key :$ref, :deep
end
parameter do
key :$ref, :branch
end
parameter do
key :$ref, :siteId
end
parameter do
key :$ref, :clusterId
end
parameter do
key :$ref, :nodeId
end
response 200 do
key :description, "The Grid'5000 node item."
content :'application/json'
end
response 404 do
key :description, "Grid'5000 node not found."
content :'text/plain'
end
end
end
protected
def collection_path
......
......@@ -13,8 +13,62 @@
# limitations under the License.
class ResourcesController < ApplicationController
include Swagger::Blocks
MAX_AGE = 60.seconds
['cluster', 'server', 'pdu', 'network_equipment'].each do |resource|
resource_id = (resource + '_id').camelize(:lower)
resources = resource.pluralize
swagger_path "/sites/{siteId}/#{resources}" do
operation :get do
key :summary, "List #{resources}"
key :description, "Fetch a collection of Grid'5000 #{resources} for a specific site."
key :tags, ['reference-api']
[:siteId, :deep, :branch, :date, :timestamp, :version].each do |param|
parameter do
key :$ref, param
end
end
response 200 do
key :description, "Grid'5000 #{resources} collection."
content :'application/json'
end
end
end
swagger_path "/sites/{siteId}/#{resources}/{#{resource_id}}" do
operation :get do
key :summary, "Get #{resource} description"
key :description, "Fetch the description of a specific #{resource}."
key :tags, ['reference-api']
parameter do
key :$ref, resource_id.to_sym
end
[:siteId, :deep, :branch, :date, :timestamp, :version].each do |param|
parameter do
key :$ref, param
end
end
response 200 do
key :description, "The Grid'5000 #{resource} item."
content :'application/json'
end
response 404 do
key :description, "Grid'5000 #{resource} not found."
content :'text/plain'
end
end
end
end
# Return a collection of resources
def index
fetch(collection_path)
......
......@@ -15,6 +15,70 @@
require 'resources_controller'
class SitesController < ResourcesController
include Swagger::Blocks
swagger_path '/sites' do
operation :get do
key :summary, 'List sites'
key :description, "Fetch a collection of Grid'5000 sites."
key :tags, ['reference-api']
[:deep, :branch, :date, :timestamp, :version].each do |param|
parameter do
key :$ref, param
end
end
response 200 do
key :description, "Grid'5000 sites collection."
content :'application/json'
end
end
end
swagger_path '/sites/{siteId}' do
operation :get do
key :summary, 'Get site description'
key :description, 'Fetch the description of a specific site.'
key :tags, ['reference-api']
[:siteId, :deep, :branch, :date, :timestamp, :version].each do |param|
parameter do
key :$ref, param
end
end
response 200 do
key :description, "The Grid'5000 site item."
content :'application/json'
end
response 404 do
key :description, "Grid'5000 site not found."
content :'text/plain'
end
end
end
swagger_path '/sites/{siteId}/status' do
operation :get do
key :summary, 'Get site status'
key :description, 'Fetch site OAR resources status and reservations.'
key :tags, ['status']
[:siteId, :statusDisks, :statusNodes, :statusVlans, :statusSubnets].each do |param|
parameter do
key :$ref, param
end
end
response 200 do
key :description, "Grid'5000 site's OAR resources status."
content :'application/json'
end
end
end
def status
# fetch valid clusters
enrich_params(params)
......
......@@ -18,6 +18,9 @@ Api::Application.routes.draw do
# The priority is based upon order of creation:
# first created -> highest priority.
# swagger doc
resources :apidocs, only: [:index]
get '/versions' => 'versions#index'
get '/versions/:id' => 'versions#show'
get '*resource/versions' => 'versions#index'
......
class Swagger::Blocks::Node
include ApplicationHelper
end
Markdown is supported
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment