(PoC) Swagger spec in comments

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

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 <[email protected]> https://intelsdi-x.herokuapp.com
+//
+//     Consumes:
+//     - application/json
+//
+//     Produces:
+//     - application/json
+//
+//
+// swagger:meta
+package v2

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))
+		})
+	})
+}

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"`
 }

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 {