Add reference and status API documentation, using Swagger

Gemfile

@@ -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

Gemfile.lock

@@ -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

app/controllers/apidocs_controller.rb

+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

app/controllers/application_controller.rb

@@ -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
 

app/controllers/clusters_controller.rb

@@ -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 = {

app/controllers/nodes_controller.rb

@@ -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

app/controllers/resources_controller.rb

@@ -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)

app/controllers/sites_controller.rb

@@ -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)

config/routes.rb

@@ -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'

lib/swagger.rb

+class Swagger::Blocks::Node
+  include ApplicationHelper
+end