diff --git a/mgmt/rest/v2/doc.go b/mgmt/rest/v2/doc.go new file mode 100644 index 000000000..893d63cdb --- /dev/null +++ b/mgmt/rest/v2/doc.go @@ -0,0 +1,43 @@ +/* +http://www.apache.org/licenses/LICENSE-2.0.txt + + +Copyright 2017 Intel Corporation + +Licensed under the Apache License, Version 2.0 (the "License"); +you may not use this file except in compliance with the License. +You may obtain a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 + +Unless required by applicable law or agreed to in writing, software +distributed under the License is distributed on an "AS IS" BASIS, +WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +See the License for the specific language governing permissions and +limitations under the License. +*/ + +// Snap API version 2 +// +// Snap is an open telemetry framework designed to simplify the collection, processing and publishing of system data through a single API. +// +// Terms Of Service: +// +// there are no TOS at this moment. +// +// Schemes: http, https +// Host: localhost +// BasePath: /v2 +// Version: 2.0.0 +// License: Apache 2.0 http://www.apache.org/licenses/LICENSE-2.0.txt +// Contact: Snap maintainers https://intelsdi-x.herokuapp.com +// +// Consumes: +// - application/json +// +// Produces: +// - application/json +// +// +// swagger:meta +package v2 diff --git a/mgmt/rest/v2/doc_test.go b/mgmt/rest/v2/doc_test.go new file mode 100644 index 000000000..e5f6e59b6 --- /dev/null +++ b/mgmt/rest/v2/doc_test.go @@ -0,0 +1,63 @@ +// +build small + +/* +http://www.apache.org/licenses/LICENSE-2.0.txt + + +Copyright 2017 Intel Corporation + +Licensed under the Apache License, Version 2.0 (the "License"); +you may not use this file except in compliance with the License. +You may obtain a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 + +Unless required by applicable law or agreed to in writing, software +distributed under the License is distributed on an "AS IS" BASIS, +WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +See the License for the specific language governing permissions and +limitations under the License. +*/ + +package v2 + +import ( + "testing" + + "github.com/go-openapi/loads" + "github.com/go-openapi/strfmt" + "github.com/go-openapi/validate" + "github.com/go-swagger/go-swagger/scan" + . "github.com/smartystreets/goconvey/convey" +) + +func TestSpec(t *testing.T) { + Convey("Swagger spec validation", t, func() { + doc, err := loads.Spec("swagger.json") + Convey("Open current swagger.json", func() { + So(err, ShouldBeNil) + So(doc, ShouldNotBeNil) + }) + err = validate.Spec(doc, strfmt.Default) + Convey("Validate local spec", func() { + So(err, ShouldBeNil) + }) + + opts := scan.Opts{ + BasePath: ".", + } + spec, err := scan.Application(opts) + Convey("Generate spec on the current project", func() { + So(err, ShouldBeNil) + So(spec, ShouldNotBeNil) + }) + + json, err := doc.Spec().MarshalJSON() + json2, err2 := spec.MarshalJSON() + Convey("Compare local spec with generated spec", func() { + So(err, ShouldBeNil) + So(err2, ShouldBeNil) + So(string(json), ShouldEqual, string(json2)) + }) + }) +} diff --git a/mgmt/rest/v2/error.go b/mgmt/rest/v2/error.go index 61bd83eee..ca0ed3482 100644 --- a/mgmt/rest/v2/error.go +++ b/mgmt/rest/v2/error.go @@ -40,8 +40,19 @@ var ( ErrWrongAction = errors.New("wrong action requested") ) -// Unsuccessful generic response to a failed API call +// Error response +// swagger:response Error +type ErrorResponse struct { + // The error message + // in: body + Body Error +} + +// Error body type Error struct { + // The error message + // + // Required: true ErrorMessage string `json:"message"` Fields map[string]string `json:"fields"` } diff --git a/mgmt/rest/v2/plugin.go b/mgmt/rest/v2/plugin.go index 78680ef3b..2b182fbc7 100644 --- a/mgmt/rest/v2/plugin.go +++ b/mgmt/rest/v2/plugin.go @@ -44,11 +44,49 @@ import ( "github.com/julienschmidt/httprouter" ) +// + +// swagger:parameters getPlugin unloadPlugin getPluginConfigItem setPluginConfigItem deletePluginConfigItem +// plugin parameters are type, name and version +// +// in: path +type PluginParams struct { + // enum: collector, processor, publisher + Type string `json:"type"` + Name string `json:"name"` + Version int `json:"version"` +} + +// swagger:parameters getPlugins +// plugin parameters are type, name and version +// +// in: query +type PluginFilter struct { + // enum: collector, processor, publisher + Type string `json:"type"` + Name string `json:"name"` +} + +// Plugins response is a list of plugins or a list of running plugins +// swagger:response PluginsResponse type PluginsResponse struct { + // in: body + Body Plugins +} + +// Plugins body +type Plugins struct { RunningPlugins []RunningPlugin `json:"running_plugins,omitempty"` Plugins []Plugin `json:"plugins,omitempty"` } +// Plugin informations +// swagger:response Plugin +type PluginResponse struct { + // in: body + Body Plugin +} + type Plugin struct { Name string `json:"name"` Version int `json:"version"` @@ -280,6 +318,14 @@ func (s *apiV2) unloadPlugin(w http.ResponseWriter, r *http.Request, p httproute Write(204, nil, w) } +// swagger:route GET /plugins plugins getPlugins +// +// List plugins +// +// Lists plugins, can be filtered by running parameters. +// +// Responses: +// 200: PluginsResponse func (s *apiV2) getPlugins(w http.ResponseWriter, r *http.Request, params httprouter.Params) { // filter by plugin name or plugin type @@ -301,7 +347,7 @@ func (s *apiV2) getPlugins(w http.ResponseWriter, r *http.Request, params httpro } else { filteredPlugins = plugins } - Write(200, PluginsResponse{RunningPlugins: filteredPlugins}, w) + Write(200, Plugins{RunningPlugins: filteredPlugins}, w) } else { // get plugins from the plugin catalog plugins := pluginCatalogBody(r.Host, s.metricManager.PluginCatalog()) @@ -316,7 +362,7 @@ func (s *apiV2) getPlugins(w http.ResponseWriter, r *http.Request, params httpro } else { filteredPlugins = plugins } - Write(200, PluginsResponse{Plugins: filteredPlugins}, w) + Write(200, Plugins{Plugins: filteredPlugins}, w) } } @@ -368,6 +414,15 @@ func pluginURI(host string, c core.Plugin) string { return fmt.Sprintf("%s://%s/%s/plugins/%s/%s/%d", protocolPrefix, host, version, c.TypeName(), c.Name(), c.Version()) } +// swagger:route GET /plugins plugins getPlugin +// +// GET plugin +// +// Get plugin information or download the plugin. +// +// Responses: +// default: Error +// 200: Plugin func (s *apiV2) getPlugin(w http.ResponseWriter, r *http.Request, p httprouter.Params) { plType, plName, plVersion, f, se := pluginParameters(p) if se != nil { diff --git a/mgmt/rest/v2/swagger.json b/mgmt/rest/v2/swagger.json new file mode 100644 index 000000000..7911891ee --- /dev/null +++ b/mgmt/rest/v2/swagger.json @@ -0,0 +1,260 @@ +{ + "consumes": [ + "application/json" + ], + "produces": [ + "application/json" + ], + "schemes": [ + "http", + "https" + ], + "swagger": "2.0", + "info": { + "description": "Snap is an open telemetry framework designed to simplify the collection, processing and publishing of system data through a single API.", + "title": "Snap API version 2", + "termsOfService": "there are no TOS at this moment.", + "contact": { + "name": "Snap maintainers", + "url": "https://intelsdi-x.herokuapp.com", + "email": "please@use.slack" + }, + "license": { + "name": "Apache 2.0", + "url": "http://www.apache.org/licenses/LICENSE-2.0.txt" + }, + "version": "2.0.0" + }, + "host": "localhost", + "basePath": "/v2", + "paths": { + "/plugins": { + "get": { + "description": "Get plugin information or download the plugin.", + "tags": [ + "plugins" + ], + "summary": "GET plugin", + "operationId": "getPlugin", + "parameters": [ + { + "enum": [ + "collector", + " processor", + " publisher" + ], + "type": "string", + "x-go-name": "Type", + "name": "type", + "in": "query" + }, + { + "type": "string", + "x-go-name": "Name", + "name": "name", + "in": "query" + }, + { + "type": "integer", + "format": "int64", + "x-go-name": "Version", + "name": "version", + "in": "query" + } + ], + "responses": { + "200": { + "$ref": "#/responses/Plugin" + }, + "default": { + "$ref": "#/responses/Error" + } + } + } + } + }, + "definitions": { + "Error": { + "description": "Error body", + "type": "object", + "required": [ + "message" + ], + "properties": { + "fields": { + "type": "object", + "additionalProperties": { + "type": "string" + }, + "x-go-name": "Fields" + }, + "message": { + "description": "The error message", + "type": "string", + "x-go-name": "ErrorMessage" + } + }, + "x-go-package": "github.com/intelsdi-x/snap/mgmt/rest/v2" + }, + "Plugin": { + "type": "object", + "properties": { + "href": { + "type": "string", + "x-go-name": "Href" + }, + "loaded_timestamp": { + "type": "integer", + "format": "int64", + "x-go-name": "LoadedTimestamp" + }, + "name": { + "type": "string", + "x-go-name": "Name" + }, + "policy": { + "type": "array", + "items": { + "$ref": "#/definitions/PolicyTable" + }, + "x-go-name": "ConfigPolicy" + }, + "signed": { + "type": "boolean", + "x-go-name": "Signed" + }, + "status": { + "type": "string", + "x-go-name": "Status" + }, + "type": { + "type": "string", + "x-go-name": "Type" + }, + "version": { + "type": "integer", + "format": "int64", + "x-go-name": "Version" + } + }, + "x-go-package": "github.com/intelsdi-x/snap/mgmt/rest/v2" + }, + "Plugins": { + "description": "Plugins body", + "type": "object", + "properties": { + "plugins": { + "type": "array", + "items": { + "$ref": "#/definitions/Plugin" + }, + "x-go-name": "Plugins" + }, + "running_plugins": { + "type": "array", + "items": { + "$ref": "#/definitions/RunningPlugin" + }, + "x-go-name": "RunningPlugins" + } + }, + "x-go-package": "github.com/intelsdi-x/snap/mgmt/rest/v2" + }, + "PolicyTable": { + "x-go-package": "github.com/intelsdi-x/snap/mgmt/rest/v2", + "$ref": "#/definitions/RuleTable" + }, + "RuleTable": { + "type": "object", + "properties": { + "default": { + "type": "object", + "x-go-name": "Default" + }, + "maximum": { + "type": "object", + "x-go-name": "Maximum" + }, + "minimum": { + "type": "object", + "x-go-name": "Minimum" + }, + "name": { + "type": "string", + "x-go-name": "Name" + }, + "required": { + "type": "boolean", + "x-go-name": "Required" + }, + "type": { + "type": "string", + "x-go-name": "Type" + } + }, + "x-go-package": "github.com/intelsdi-x/snap/control/plugin/cpolicy" + }, + "RunningPlugin": { + "type": "object", + "properties": { + "hitcount": { + "type": "integer", + "format": "int64", + "x-go-name": "HitCount" + }, + "href": { + "type": "string", + "x-go-name": "Href" + }, + "id": { + "type": "integer", + "format": "uint32", + "x-go-name": "ID" + }, + "last_hit_timestamp": { + "type": "integer", + "format": "int64", + "x-go-name": "LastHitTimestamp" + }, + "name": { + "type": "string", + "x-go-name": "Name" + }, + "pprof_port": { + "type": "string", + "x-go-name": "PprofPort" + }, + "type": { + "type": "string", + "x-go-name": "Type" + }, + "version": { + "type": "integer", + "format": "int64", + "x-go-name": "Version" + } + }, + "x-go-package": "github.com/intelsdi-x/snap/mgmt/rest/v2" + } + }, + "responses": { + "Error": { + "description": "Error response", + "schema": { + "$ref": "#/definitions/Error" + } + }, + "Plugin": { + "description": "Plugin informations", + "schema": { + "$ref": "#/definitions/Plugin" + } + }, + "PluginsResponse": { + "description": "Plugins response is a list of plugins or a list of running plugins", + "schema": { + "$ref": "#/definitions/Plugins" + } + } + } +} diff --git a/mgmt/rest/v2/task.go b/mgmt/rest/v2/task.go index 77e13c0b2..6c1f2d245 100644 --- a/mgmt/rest/v2/task.go +++ b/mgmt/rest/v2/task.go @@ -37,6 +37,14 @@ type TasksResponse struct { Tasks Tasks `json:"tasks"` } +// swagger:parameters getTask watchTask updateTaskState removeTask +type TaskID struct { + // plugin version + // + // in: path + ID string `json:"id"` +} + type Task struct { ID string `json:"id"` Name string `json:"name"`