Commit d251cf82 authored by Samir Noir's avatar Samir Noir 🧀
Browse files

Merge branch 'features/#7049' into 'master'

Add OpenAPI documentation spec

See merge request !83
parents 3f4959e2 7ff30d40
Pipeline #192990 waiting for manual action with stages
in 21 minutes and 52 seconds
......@@ -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, "This is the user and developer documentation for the Grid'5000 "\
"API. The API allows to facilitate interractions and automation with Grid'5000."
contact do
key :name, 'support-staff@lists.grid5000.fr'
end
end
server do
key :url, 'https://api.grid5000.fr/'
end
security do
key :BasicAuth, []
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, 'version'
key :description, 'The version API allows to consult reference-repository history.'
end
tag do
key :name, 'status'
key :description, "Status API allows to known the state of OAR's resources "\
"(like nodes, disks, vlans, subnets). The current and upcoming "\
"reservations are also returned by this API."
end
tag do
key :name, 'job'
key :description, "The job API is used to submit a job on Grid'5000 "\
"or to manage an existing one. This API use OAR, more informations "\
"about job management on Grid'5000 can be found on [the wiki]"\
"(https://www.grid5000.fr/w/Advanced_OAR)"
end
tag do
key :name, 'deployment'
key :description, 'The deployment API is use if you want to deploy a specific '\
'environment image on the nodes you have reserved. It uses the Kadeploy tool.'
end
tag do
key :name, 'vlan'
key :description, "The vlan API allows to get informations about vlans and to "\
"manipulate them. For example, it is possible to put deployed nodes in "\
"reserved vlans, to fetch current vlans and nodes status or to start or "\
"stop dhcp servers.\nThe associated documentation about Kavlan can be found "\
"on [Grid'5000's wiki](https://www.grid5000.fr/w/KaVLAN)"
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
schema do
key :type, :boolean
end
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
schema do
key :type, :string
end
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
schema do
key :type, :integer
end
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
schema do
key :type, :string
key :format, :'date-time'
end
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
schema do
key :type, :string
key :default, 'master'
end
end
parameter :limit do
key :name, :limit
key :in, :query
key :description, 'Limit the number of items to return.'
key :required, false
schema do
key :type, :integer
end
end
parameter :offset do
key :name, :offset
key :in, :query
key :description, 'Paginate through the collection with multiple requests.'
key :required, false
schema do
key :type, :integer
end
end
['cluster', 'site', 'node', 'server', 'pdu', 'network_equipment'].each do |resource|
resource_id = (resource + '_id').camelize(:lower)
parameter resource_id.to_sym do
key :name, resource_id.to_sym
key :in, :path
key :description, "#{resource.titleize}'s ID."
key :required, true
schema do
key :type, :string
end
end
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
schema do
key :type, :string
key :pattern, '^(no|yes)$'
key :default, 'yes'
end
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
schema do
key :type, :string
key :pattern, '^(no|yes)$'
key :default, 'yes'
end
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
schema do
key :type, :string
key :pattern, '^(no|yes)$'
key :default, 'yes'
end
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
schema do
key :type, :string
key :pattern, '^(no|yes)$'
key :default, 'yes'
end
end
schema :BaseApiCollection do
key :required, [:total, :offset]
property :total do
key :type, :integer
key :description, 'The number of items in collection.'
end
property :offset do
key :type, :integer
key :description, 'The offset (for pagination).'
end
end
schema :Links do
key :required, [:rel, :href, :type]
property :rel do
key :type, :string
key :description, "The relationship's name."
key :example, 'parent'
end
property :href do
key :type, :string
key :description, "The link to the resource."
key :example, '/3.0/sites/grenoble'
end
property :type do
key :type, :string
key :description, "The resource's type, can be an item or an item collection."
key :example, 'application/vnd.grid5000.item+json'
end
end
security_scheme :BasicAuth do
key :type, :http
key :scheme, :basic
end
end
# A list of all classes that have swagger_* declarations.
SWAGGERED_CLASSES = [
SitesController,
ClustersController,
ResourcesController,
VersionsController,
DeploymentsController,
JobsController,
VlansController,
VlansUsersController,
VlansUsersAllController,
VlansNodesController,
VlansNodesAllController,
Grid5000::Deployment,
Grid5000::Job,
Grid5000::Kavlan,
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 = {
......
......@@ -13,9 +13,72 @@
# limitations under the License.
class DeploymentsController < ApplicationController
include Swagger::Blocks
LIMIT = 50
LIMIT_MAX = 500
swagger_path "/sites/{siteId}/deployments" do
operation :get do
key :summary, 'List deployments'
key :description, 'Fetch the list of all the deployments created for site. '\
'By default, the last 50 deployments are returned.'
key :tags, ['deployment']
[:siteId, :offset, :limit, :deployReverse, :deployStatus, :deployUser].each do |param|
parameter do
key :$ref, param
end
end
response 200 do
content :'application/json' do
schema do
key :'$ref', :DeploymentCollection
end
end
key :description, 'Deployment collection.'
end
end
operation :post do
key :summary, 'Submit deployment'
key :description, "Submit a new deployment (requires a job deploy reservation)."
key :tags, ['deployment']
parameter do
key :$ref, :siteId
end
request_body do
key :description, 'Deployment creation object.'
key :required, true
content 'application/json' do
schema do
key :'$ref', :DeploymentSubmit
end
end
content 'application/x-www-form-urlencoded' do
schema do
key :'$ref', :DeploymentSubmit
end
end
end
response 201 do
content :'plain/text'
key :description, 'Deployment successfully created.'
header :'Location' do
key :description, 'Location of the new deployment resource.'
schema do
key :type, :string
end
end
end
end
end
# List deployments
def index
allow :get, :post; vary_on :accept
......@@ -50,6 +113,57 @@ class DeploymentsController < ApplicationController
end
end
swagger_path "/sites/{siteId}/deployments/{deploymentId}" do
operation :get do
key :summary, 'Get deployment'
key :description, 'Fetch a specific deployment.'
key :tags, ['deployment']
[:siteId, :deploymentId].each do |param|
parameter do
key :$ref, param
end
end
response 200 do
content :'application/json' do
schema do
key :'$ref', :Deployment
end
end
key :description, 'The deployment item.'
end
response 404 do
content :'text/plain'
key :description, 'Deployment not found.'
end
end
operation :delete do
key :summary, 'Cancel deployment.'
key :description, 'Cancel a deployment.'
key :tags, ['deployment']
[:siteId, :deploymentId].each do |param|
parameter do
key :$ref, param
end
end
response 204 do
key :description, 'Deployment successfully canceled.'
header :'Location' do
key :description, 'Location of the new deployment resource'
schema do
key :type, :string
end
end
end
end
end
# Display the details of a deployment
def show
allow :get, :delete, :put; vary_on :accept
......
......@@ -13,9 +13,73 @@
# limitations under the License.
class JobsController < ApplicationController
include Swagger::Blocks
LIMIT = 50
LIMIT_MAX = 500
swagger_path "/sites/{siteId}/jobs" do
operation :get do
key :summary, 'List jobs'
key :description, 'Fetch the list of all jobs for site. Jobs ordering is by ' \
'descending date of submission.'
key :tags, ['job']
[:siteId, :offset, :limit, :jobQueue, :jobName, :jobState,
:jobUser, :jobResources].each do |param|
parameter do
key :$ref, param
end
end
response 200 do
content :'application/json' do
schema do
key :'$ref', :JobCollection
end
end
key :description, 'Deployment collection.'
end
end
operation :post do
key :summary, 'Submit job'
key :description, "Submit a new job."
key :tags, ['job']
parameter do
key :$ref, :siteId
end
request_body do
key :description, 'Job submission payload.'
key :required, true
content 'application/json' do
schema do
key :'$ref', :JobSubmit
end
end
content 'application/x-www-form-urlencoded' do
schema do
key :'$ref', :JobSubmit
end
end
end
response 201 do
content :'plain/text'
key :description, 'Job successfully created.'
header :'Location' do
key :description, 'Location of the new job.'
schema do
key :type, :string
end
end
end
end
end
# List jobs
def index
allow :get, :post; vary_on :accept
......@@ -60,6 +124,58 @@ class JobsController < ApplicationController
end
end
swagger_path "/sites/{siteId}/jobs/{jobId}" do
operation :get do
key :summary, 'Get job'
key :description, 'Fetch a specific job.'
key :tags, ['job']
[:siteId, :jobId].each do |param|
parameter do
key :$ref, param
end
end
response 200 do
content :'application/json' do
schema do
key :'$ref', :Job
end
end
key :description, 'The job item.'
end
response 404 do
content :'text/plain'
key :description, 'Job not found.'
end
end
operation :delete do
key :summary, 'Delete job'
key :description, 'Ask for deletion of job.'
key :tags, ['job']
[:siteId, :jobId].each do |param|
parameter do
key :$ref, param
end
end
response 202 do
key :description, 'Job deletion accepted. Note that the deletion is not '\
'immediate, the job can be poll until error state.'
header :'Location' do
key :description, 'Location of the job resource'
schema do
key :type, :string
end
end
end
end
end
# Display the details of a job
def show
allow :get, :delete; vary_on :accept
......
......@@ -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']