Skip to content
This repository was archived by the owner on Nov 8, 2022. It is now read-only.

Commit

Permalink
Document Snap with valid swagger spec
Browse files Browse the repository at this point in the history
  • Loading branch information
@candysmurf
candysmurf committed Apr 11, 2017
1 parent 74b20af commit de3daa4
Show file tree
Hide file tree
Showing 21 changed files with 2,044 additions and 147 deletions.
4 changes: 3 additions & 1 deletion .travis.yml
View file
Original file line number Diff line number Diff line change
@@ -1,10 +1,12 @@
sudo: false
sudo: true
language: go
go:
- 1.7.3
before_install:
- bash scripts/gitcookie.sh
- go get github.com/smartystreets/goconvey/convey
- echo "deb https://dl.bintray.com/go-swagger/goswagger-debian ubuntu main" | sudo tee -a /etc/apt/sources.list
- sudo apt-get update && sudo apt-get install -y swagger --force-yes
- if [ ! -d $SNAP_SOURCE ]; then mkdir -p $HOME/gopath/src/github.com/intelsdi-x; ln -s $TRAVIS_BUILD_DIR $SNAP_SOURCE; fi # CI for forks not from intelsdi-x
env:
global:
Expand Down
3 changes: 3 additions & 0 deletions Makefile
View file
Original file line number Diff line number Diff line change
Expand Up @@ -22,6 +22,7 @@ default:
$(MAKE) deps
$(MAKE) snap
$(MAKE) plugins
$(MAKE) swagger
deps:
bash -c "./scripts/deps.sh"
test:
Expand Down Expand Up @@ -59,3 +60,5 @@ install:
cp build/$(OS)/$(ARCH)/snaptel /usr/local/bin/
proto:
cd `echo $(GOPATH) | cut -d: -f 1`; bash -c "./src/github.com/intelsdi-x/snap/scripts/gen-proto.sh"
swagger:
bash -c "./scripts/swagger.sh"
10 changes: 8 additions & 2 deletions core/schedule.go
View file
Original file line number Diff line number Diff line change
Expand Up @@ -27,9 +27,15 @@ import (
"github.com/intelsdi-x/snap/pkg/schedule"
)

// Schedule defines a scheduler.
//
// swagger:model Schedule
type Schedule struct {
Type string `json:"type,omitempty"`
Interval string `json:"interval,omitempty"`
// required: true
// enum: simple, windowed, streaming, cron
Type string `json:"type"`
// required: true
Interval string `json:"interval"`
StartTimestamp *time.Time `json:"start_timestamp,omitempty"`
StopTimestamp *time.Time `json:"stop_timestamp,omitempty"`
Count uint `json:"count,omitempty"`
Expand Down
31 changes: 31 additions & 0 deletions doc.go
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,31 @@
// Package main Snap Restful APIs.
//
// Snap is an open telemetry framework designed to simplify the collection,
// processing and publishing of system data through a single API.
//
// This specification should demonstrate a fully compliant swagger 2.0 spec for Snap.
// It lists all the possible Snap Restful APIs that are available for use,
// testing or generating spec compatible clients.
//
// Terms Of Service:
//
// There are no TOS at this moment, use at your own risk we take no responsibility.
//
// Schemes: http, https
// Host: 127.0.0.1:8181
// BasePath: /v2
// Version: 1.1.0
// License: Apache 2.0 http://www.apache.org/licenses/
// Contact: Snap Maintainer<[email protected]> https://github.com/intelsdi-x/snap
//
// Consumes:
// - application/json
// - application/x-protobuf
//
// Produces:
// - application/json
// - application/x-protobuf
//
//
// swagger:meta
package main
289 changes: 283 additions & 6 deletions mgmt/rest/v2/api.go
View file
Original file line number Diff line number Diff line change
Expand Up @@ -56,25 +56,302 @@ func New(wg *sync.WaitGroup, killChan chan struct{}, protocol string) *apiV2 {

func (s *apiV2) GetRoutes() []api.Route {
routes := []api.Route{
// plugin routes
// swagger:route GET /plugins plugins getPlugins
//
// Get All
//
// An empty list is returned if there are no loaded plugins.
//
// Consumes:
// application/json
// application/x-protobuf
//
// Produces:
// application/json
// application/x-protobuf
//
// Schemes: http, https
//
// Responses:
// 200: PluginsResponse
api.Route{Method: "GET", Path: prefix + "/plugins", Handle: s.getPlugins},
// swagger:route GET /plugins/{ptype}/{pname}/{pversion} plugins getPlugin
//
// Get
//
// An error will be returned if the plugin does not exist.
//
// Consumes:
// application/json
// application/x-protobuf
//
// Produces:
// application/json
// application/x-protobuf
//
// Schemes: http, https
//
// Responses:
// 200: PluginResponse
// 400: ErrorResponse
// 404: ErrorResponse
// 500: ErrorResponse
api.Route{Method: "GET", Path: prefix + "/plugins/:type/:name/:version", Handle: s.getPlugin},
// swagger:route POST /plugins plugins loadPlugin
//
// Load
//
// A plugin binary is required.
//
// Consumes:
// application/json
// application/x-protobuf
// multipart/form-data
//
// Produces:
// application/json
// application/x-protobuf
// multipart/form-data
//
// Schemes: http, https
//
// Responses:
// 201: PluginResponse
// 400: ErrorResponse
// 409: ErrorResponse
// 415: ErrorResponse
// 500: ErrorResponse
api.Route{Method: "POST", Path: prefix + "/plugins", Handle: s.loadPlugin},
// swagger:route DELETE /plugins/{ptype}/{pname}/{pversion} plugins unloadPlugin
//
// Unload
//
// Required fields are plugin type, name and version.
//
// Consumes:
// application/json
// application/x-protobuf
// text/plain
//
// Produces:
// application/json
// application/x-protobuf
// text/plain
//
// Schemes: http, https
//
// Responses:
// 204: PluginResponse
// 400: ErrorResponse
// 404: ErrorResponse
// 409: ErrorResponse
// 500: ErrorResponse
api.Route{Method: "DELETE", Path: prefix + "/plugins/:type/:name/:version", Handle: s.unloadPlugin},

// swagger:route GET /plugins/{ptype}/{pname}/{pversion}/config plugins getPluginConfigItem
//
// Get Config
//
// An empty config is returned if there are no configs for the plugin.
//
// Consumes:
// application/json
// application/x-protobuf
//
// Produces:
// application/json
// application/x-protobuf
//
// Schemes: http, https
//
// Responses:
// 200: PluginConfigResponse
// 400: ErrorResponse
api.Route{Method: "GET", Path: prefix + "/plugins/:type/:name/:version/config", Handle: s.getPluginConfigItem},
// swagger:route PUT /plugins/{ptype}/{pname}/{pversion}/config plugins setPluginConfigItem
//
// Set Config
//
// A config is JSON. For example: {"user":"snap", "host":"ocean_eleven"}.
//
// Consumes:
// application/json
// application/x-protobuf
//
// Produces:
// application/json
// application/x-protobuf
//
// Schemes: http, https
//
// Responses:
// 200: PluginConfigResponse
// 400: ErrorResponse
api.Route{Method: "PUT", Path: prefix + "/plugins/:type/:name/:version/config", Handle: s.setPluginConfigItem},
// swagger:route DELETE /plugins/{ptype}/{pname}/{pversion}/config plugins deletePluginConfigItem
//
// Delete Config
//
// A minimum of one config key is required for this operation.
//
// Consumes:
// application/json
// application/x-protobuf
//
// Produces:
// application/json
// application/x-protobuf
//
// Schemes: http, https
//
// Responses:
// 200: PluginConfigResponse
// 400: ErrorResponse
api.Route{Method: "DELETE", Path: prefix + "/plugins/:type/:name/:version/config", Handle: s.deletePluginConfigItem},

// metric routes
// swagger:route GET /metrics plugins getMetrics
//
// Get Metrics
//
// An empty list returns if there is no loaded metrics.
//
// Consumes:
// application/json
// application/x-protobuf
//
// Produces:
// application/json
// application/x-protobuf
//
// Schemes: http, https
//
// Responses:
// 200: MetricsResponse
// 404: ErrorResponse
// 500: ErrorResponse
api.Route{Method: "GET", Path: prefix + "/metrics", Handle: s.getMetrics},

// task routes
// swagger:route GET /tasks tasks getTasks
//
// Get All
//
// An empty list returns if no tasks exist.
//
// Consumes:
// application/json
// application/x-protobuf
//
// Produces:
// application/json
// application/x-protobuf
//
// Schemes: http, https
//
// Responses:
// 200: TasksResponse
api.Route{Method: "GET", Path: prefix + "/tasks", Handle: s.getTasks},
// swagger:route GET /tasks/{id} tasks getTask
//
// Get
//
// The task ID is required.
//
// Consumes:
// application/json
// application/x-protobuf
//
// Produces:
// application/json
// application/x-protobuf
//
// Schemes: http, https
//
// Responses:
// 200: TaskResponse
// 404: ErrorResponse
api.Route{Method: "GET", Path: prefix + "/tasks/:id", Handle: s.getTask},
// swagger:route GET /tasks/{id}/watch tasks watchTask
//
// Watch
//
// The task ID is required.
//
// Consumes:
// application/json
// application/x-protobuf
// text/event-stream
//
// Produces:
// application/json
// application/x-protobuf
// text/event-stream
//
// Schemes: http, https
//
// Responses:
// 200: TaskWatchResponse
// 404: ErrorResponse
// 500: ErrorResponse
api.Route{Method: "GET", Path: prefix + "/tasks/:id/watch", Handle: s.watchTask},
// swagger:route POST /tasks tasks addTask
//
// Add
//
// A string representation of Snap task manifest is required.
//
// Consumes:
// application/json
// application/x-protobuf
//
// Produces:
// application/json
// application/x-protobuf
//
// Schemes: http, https
//
// Responses:
// 201: TaskResponse
// 500: ErrorResponse
api.Route{Method: "POST", Path: prefix + "/tasks", Handle: s.addTask},
// swagger:route PUT /tasks/{id} tasks updateTaskState
//
// Enable/Start/Stop
//
// The task ID is required.
//
// Consumes:
// application/json
// application/x-protobuf
//
// Produces:
// application/json
// application/x-protobuf
//
// Schemes: http, https
//
// Responses:
// 204: TaskResponse
// 400: ErrorResponse
// 409: ErrorResponse
// 500: ErrorResponse
api.Route{Method: "PUT", Path: prefix + "/tasks/:id", Handle: s.updateTaskState},
// swagger:route DELETE /tasks/{id} tasks removeTask
//
// Remove
//
// The task ID is required.
//
// Consumes:
// application/json
// application/x-protobuf
//
// Produces:
// application/json
// application/x-protobuf
//
// Schemes: http, https
//
// Responses:
// 204: TaskResponse
// 404: ErrorResponse
// 500: TaskErrorResponse
api.Route{Method: "DELETE", Path: prefix + "/tasks/:id", Handle: s.removeTask},
}
return routes
Expand Down
Loading

0 comments on commit de3daa4

Please sign in to comment.