diff --git a/glide.lock b/glide.lock index 657eef957..6d9084eaf 100644 --- a/glide.lock +++ b/glide.lock @@ -1,5 +1,5 @@ -hash: 55584a3098467b96c2800b810444ba49663ade021e4f2d0796233b277d712415 -updated: 2016-11-22T14:54:43.026574122-08:00 +hash: e287e5a53fe2f50a9da6ed789f038a8ddc45330c1ff8eadfe452c73e62ff0a82 +updated: 2017-01-27T10:07:17.754839281-08:00 imports: - name: github.com/appc/spec version: db96f94ae6b227fe4d8288527ead8927181620f6 @@ -20,6 +20,18 @@ imports: - semver - name: github.com/ghodss/yaml version: c3eb24aeea63668ebdac08d2e252f20df8b6b1ae +- name: github.com/go-openapi/loads + version: 6bb6486231e079ea125c0f39994ed3d0c53399ed + subpackages: + - fmts +- name: github.com/go-openapi/strfmt + version: 0cb3db44c13bad3b3f567b762a66751972a310cc +- name: github.com/go-openapi/validate + version: 035dcd74f1f61e83debe1c22950dc53556e7e4b2 +- name: github.com/go-swagger/go-swagger + version: 04e27555375e7d9a3251bfb35fcb9ae13cec99a1 + subpackages: + - scan - name: github.com/gogo/protobuf version: 82d16f734d6d871204a3feb1a73cb220cc92574c subpackages: @@ -88,6 +100,7 @@ imports: - context - http2 - http2/hpack + - idna - internal/timeseries - lex/httplex - trace @@ -117,12 +130,38 @@ imports: - pkg/conversion - third_party/forked/reflect testImports: +- name: github.com/go-openapi/analysis + version: d5a75b7d751ca3f11ad5d93cfe97405f2c3f6a47 +- name: github.com/go-openapi/errors + version: fc3f73a224499b047eda7191e5d22e1e9631e86f +- name: github.com/go-openapi/jsonpointer + version: 779f45308c19820f1a69e9a4cd965f496e0da10f +- name: github.com/go-openapi/jsonreference + version: 36d33bfe519efae5632669801b180bf1a245da3b +- name: github.com/go-openapi/runtime + version: 3b13ebb46790d871d74a6c2450fa4b1280f90854 +- name: github.com/go-openapi/spec + version: f81e0f768713035fe232cd0d44a1c56e4eef1383 +- name: github.com/go-openapi/swag + version: 96d7b9ebd181a1735a1c9ac87914f2b32fbf56c9 - name: github.com/gopherjs/gopherjs version: 4b53e1bddba0e2f734514aeb6c02db652f4c6fe8 subpackages: - js - name: github.com/jtolds/gls version: 8ddce2a84170772b95dd5d576c48d517b22cac63 +- name: github.com/mailru/easyjson + version: edd3ef1dab48f1cc831d78c0602a79be7a7b1a5e + subpackages: + - buffer + - jlexer + - jwriter +- name: github.com/mitchellh/mapstructure + version: db1efb556f84b25a0a13a04aad883943538ad2e0 +- name: github.com/PuerkitoBio/purell + version: 0bcb03f4b4d0a9428594752bd2a3b9aa0a9d4bd4 +- name: github.com/PuerkitoBio/urlesc + version: 5bd2802263f21d8788851d5305584c82a5c75d7e - name: github.com/smartystreets/assertions version: 443d812296a84445c202c085f19e18fc238f8250 subpackages: @@ -134,3 +173,15 @@ testImports: - convey - convey/gotest - convey/reporting +- name: golang.org/x/text + version: ece019dcfd29abcf65d0d1dfe145e8faad097640 + subpackages: + - transform + - unicode/norm + - width +- name: golang.org/x/tools + version: f8ed2e405fdcbb42c55233531ad98721e6d1cb3e + subpackages: + - go/ast/astutil + - go/buildutil + - go/loader diff --git a/glide.yaml b/glide.yaml index 00978ad22..2b27829bb 100644 --- a/glide.yaml +++ b/glide.yaml @@ -53,3 +53,7 @@ import: version: c1cd2254a6dd314c9d73c338c12688c9325d85c6 - package: github.com/intelsdi-x/snap-plugin-lib-go - package: github.com/intelsdi-x/snap-plugin-utilities +- package: github.com/go-openapi/loads +- package: github.com/go-openapi/strfmt +- package: github.com/go-openapi/validate +- package: github.com/go-swagger/go-swagger/scan \ No newline at end of file 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..bb80fac1e 100644 --- a/mgmt/rest/v2/plugin.go +++ b/mgmt/rest/v2/plugin.go @@ -44,11 +44,59 @@ import ( "github.com/julienschmidt/httprouter" ) +// PluginParams contains plugin type, name and version in the path. +// +// swagger:parameters getPlugin unloadPlugin getPluginConfigItem setPluginConfigItem deletePluginConfigItem +type PluginParams struct { + // plugin parameters + + // Plugin type + // + // in: path + // enum: collector, processor, publisher + Ptype string `json:"ptype"` + + // Plugin name + // + // in: path + Pname string `json:"pname"` + + // Plugin version + // + // in: path + Pversion int `json:"pversion"` +} + +// 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 +328,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 +357,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 +372,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 +424,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/{ptype}/{pname}/{pversion} 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..8d298bf2a --- /dev/null +++ b/mgmt/rest/v2/swagger.json @@ -0,0 +1,297 @@ +{ + "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": "Lists plugins, can be filtered by running parameters.", + "tags": [ + "plugins" + ], + "summary": "List plugins", + "operationId": "getPlugins", + "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" + } + ], + "responses": { + "200": { + "$ref": "#/responses/PluginsResponse" + } + } + } + }, + "/plugins/{ptype}/{pname}/{pversion}": { + "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": "Ptype", + "description": "Plugin type", + "name": "ptype", + "in": "path" + }, + { + "type": "string", + "x-go-name": "Pname", + "description": "Plugin name", + "name": "pname", + "in": "path" + }, + { + "type": "integer", + "format": "int64", + "x-go-name": "Pversion", + "description": "Plugin version", + "name": "pversion", + "in": "path" + } + ], + "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"`