Skip to content

Commit a503bfd

Browse files
lebaucelebauce
committed
api: add swagger definitions
1 parent 9a753c9 commit a503bfd

20 files changed

+581
-52
lines changed

‎agent/agent.go

+5-1
Original file line numberDiff line numberDiff line change
@@ -89,7 +89,11 @@ func NewAnalyzerStructClientPool(authOpts *shttp.AuthenticationOpts) (*ws.Struct
8989
return pool, nil
9090
}
9191

92-
// Status represents the status of an agent
92+
// Status agent object
93+
//
94+
// Status describes the status of an agent
95+
//
96+
// swagger:model AgentStatus
9397
type Status struct {
9498
Clients map[string]ws.ConnStatus
9599
Analyzers map[string]pod.ConnStatus

‎analyzer/server.go

+4
Original file line numberDiff line numberDiff line change
@@ -68,7 +68,11 @@ type ElectionStatus struct {
6868
IsMaster bool
6969
}
7070

71+
// Status analyzer object
72+
//
7173
// Status describes the status of an analyzer
74+
//
75+
// swagger:model AnalyzerStatus
7276
type Status struct {
7377
Agents map[string]ws.ConnStatus
7478
Peers hub.PeersStatus

‎api/server/alert.go

+3
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,6 @@
1+
//go:generate sh -c "renderizer --name=alert --resource=alert --type=Alert --title=Alert --article=an swagger_operations.tmpl > alert_swagger.go"
2+
//go:generate sh -c "renderizer --name=alert --resource=alert --type=Alert --title=Alert swagger_definitions.tmpl > alert_swagger.json"
3+
14
/*
25
* Copyright (C) 2016 Red Hat, Inc.
36
*

‎api/server/capture.go

+3
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,6 @@
1+
//go:generate sh -c "renderizer --name=capture --resource=capture --type=Capture --title=Capture --article=a swagger_operations.tmpl > capture_swagger.go"
2+
//go:generate sh -c "renderizer --name=capture --resource=capture --type=Capture --title=Capture --article=a swagger_definitions.tmpl > capture_swagger.json"
3+
14
/*
25
* Copyright (C) 2016 Red Hat, Inc.
36
*

‎api/server/config.go

+29
Original file line numberDiff line numberDiff line change
@@ -35,6 +35,35 @@ func (c *configAPI) configGet(w http.ResponseWriter, r *auth.AuthenticatedReques
3535
}
3636

3737
func (c *configAPI) registerEndpoints(r *shttp.Server, authBackend shttp.AuthenticationBackend) {
38+
// swagger:operation GET /config/{key} getConfig
39+
//
40+
// Get configuration value
41+
//
42+
// ---
43+
// summary: Get configuration
44+
//
45+
// tags:
46+
// - Config
47+
//
48+
// produces:
49+
// - application/json
50+
//
51+
// schemes:
52+
// - http
53+
// - https
54+
//
55+
// parameters:
56+
// - name: key
57+
// in: path
58+
// required: true
59+
// type: string
60+
//
61+
// responses:
62+
// 200:
63+
// description: configuration value
64+
// schema:
65+
// $ref: '#/definitions/AnyValue'
66+
3867
routes := []shttp.Route{
3968
{
4069
Name: "ConfigGet",

‎api/server/edgerule.go

+3
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,6 @@
1+
//go:generate sh -c "renderizer --name='edge rule' --resource=edgerule --type=EdgeRule --title='Edge rule' --article=an swagger_operations.tmpl > edgerule_swagger.go"
2+
//go:generate sh -c "renderizer --name='edge rule' --resource=edgerule --type=EdgeRule --title='Edge rule' swagger_definitions.tmpl > edgerule_swagger.json"
3+
14
/*
25
* Copyright (C) 2018 Red Hat, Inc.
36
*

‎api/server/noderule.go

+3
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,6 @@
1+
//go:generate sh -c "renderizer --name='node rule' --resource=noderule --type=NodeRule --title='Node rule' --article=a swagger_operations.tmpl > noderule_swagger.go"
2+
//go:generate sh -c "renderizer --name='node rule' --resource=noderule --type=NodeRule --title='Node rule' swagger_definitions.tmpl > noderule_swagger.json"
3+
14
/*
25
* Copyright (C) 2018 Red Hat, Inc.
36
*

‎api/server/packet_injector.go

+3
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,6 @@
1+
//go:generate sh -c "renderizer --name=injection --resource=injectpacket --type=PacketInjection --title='Injection' --article=an swagger_operations.tmpl > packet_injector_swagger.go"
2+
//go:generate sh -c "renderizer --name=injection --resource=injectpacket --type=PacketInjection --title='Injection' swagger_definitions.tmpl > packet_injector_swagger.json"
3+
14
/*
25
* Copyright (C) 2016 Red Hat, Inc.
36
*

‎api/server/pcap.go

+31
Original file line numberDiff line numberDiff line change
@@ -86,6 +86,37 @@ func (p *PcapAPI) registerEndpoints(r *shttp.Server, authBackend shttp.Authentic
8686

8787
// RegisterPcapAPI registers a new pcap injector API
8888
func RegisterPcapAPI(r *shttp.Server, store storage.Storage, authBackend shttp.AuthenticationBackend) {
89+
// swagger:operation POST /pcap injectPCAP
90+
//
91+
// Inject PCAP
92+
//
93+
// ---
94+
// summary: Inject PCAP
95+
//
96+
// tags:
97+
// - PCAP
98+
//
99+
// consumes:
100+
// - application/octet-stream
101+
//
102+
// schemes:
103+
// - http
104+
// - https
105+
//
106+
// parameters:
107+
// - in: body
108+
// name: status
109+
// required: true
110+
// schema:
111+
// type: string
112+
// format: binary
113+
//
114+
// responses:
115+
// 202:
116+
// description: request accepted
117+
// 400:
118+
// description: invalid PCAP
119+
89120
p := &PcapAPI{
90121
Storage: store,
91122
}

‎api/server/server.go

+50-1
Original file line numberDiff line numberDiff line change
@@ -15,6 +15,25 @@
1515
*
1616
*/
1717

18+
// Package server Skydive API
19+
//
20+
// The Skydive REST API allows to communicate with a Skydive analyzer.
21+
//
22+
// Schemes: http, https
23+
// Host: localhost:8082
24+
// BasePath: /api
25+
// Version: 0.24.0
26+
// License: Apache http://opensource.org/licenses/Apache-2.0
27+
// Contact: Skydive mailing list <[email protected]>
28+
//
29+
// Consumes:
30+
// - application/json
31+
//
32+
// Produces:
33+
// - application/json
34+
// - text/plain
35+
//
36+
// swagger:meta
1837
package server
1938

2039
import (
@@ -51,9 +70,13 @@ type Server struct {
5170
}
5271

5372
// Info for each host describes his API version and service (agent or analyzer)
73+
// swagger:model
5474
type Info struct {
55-
Host string
75+
// Server host ID
76+
Host string
77+
// API version
5678
Version string
79+
// Service type
5780
Service string
5881
}
5982

@@ -230,6 +253,32 @@ func (a *Server) RegisterAPIHandler(handler Handler, authBackend shttp.Authentic
230253
}
231254

232255
func (a *Server) addAPIRootRoute(service common.Service, authBackend shttp.AuthenticationBackend) {
256+
// swagger:operation GET / getApi
257+
//
258+
// Get API version
259+
//
260+
// ---
261+
// summary: Get API info
262+
//
263+
// tags:
264+
// - API Info
265+
//
266+
// consumes:
267+
// - application/json
268+
//
269+
// produces:
270+
// - application/json
271+
//
272+
// schemes:
273+
// - http
274+
// - https
275+
//
276+
// responses:
277+
// 200:
278+
// description: API info
279+
// schema:
280+
// $ref: '#/definitions/Info'
281+
233282
info := Info{
234283
Version: version.Version,
235284
Service: string(service.Type),

‎api/server/status.go

+30
Original file line numberDiff line numberDiff line change
@@ -34,6 +34,36 @@ func (s *statusAPI) statusGet(w http.ResponseWriter, r *auth.AuthenticatedReques
3434
}
3535

3636
func (s *statusAPI) registerEndpoints(r *shttp.Server, authBackend shttp.AuthenticationBackend) {
37+
// swagger:operation GET /status getStatus
38+
//
39+
// Get status
40+
//
41+
// ---
42+
// summary: Get status
43+
//
44+
// tags:
45+
// - Status
46+
//
47+
// consumes:
48+
// - application/json
49+
//
50+
// produces:
51+
// - application/json
52+
//
53+
// schemes:
54+
// - http
55+
// - https
56+
//
57+
// responses:
58+
// 200:
59+
// description: Status
60+
// content:
61+
// application/json:
62+
// schema:
63+
// anyOf:
64+
// - $ref: '#/definitions/AgentStatus'
65+
// - $ref: '#/definitions/AnalyzerStatus'
66+
3767
routes := []shttp.Route{
3868
{
3969
Name: "StatusGet",

‎api/server/swagger_definitions.tmpl

+18
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,18 @@
1+
{
2+
"tags": [ {
3+
"name": "{{ .Title }}s",
4+
"description": "{{ .Title }}"
5+
} ],
6+
"definitions": {
7+
"AnyValue": {},
8+
"{{ .Type }}s": {
9+
"description": "{{ .Title }}s",
10+
"type": "object",
11+
"title": "Map of {{ .Name }}s",
12+
"x-additionalPropertiesName": "UUID",
13+
"additionalProperties": {
14+
"$ref": "#/definitions/{{ .Type }}"
15+
}
16+
}
17+
}
18+
}

‎api/server/swagger_operations.tmpl

+130
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,130 @@
1+
// Code generated by renderizer for swagger. DO NOT EDIT.
2+
3+
// swagger:operation GET /{{ .Resource }} list{{ .Type }}s
4+
//
5+
// List {{ .Name }}s
6+
//
7+
// ---
8+
// summary: List {{ .Name }}s
9+
//
10+
// tags:
11+
// - {{ .Title }}s
12+
//
13+
// consumes:
14+
// - application/json
15+
//
16+
// produces:
17+
// - application/json
18+
//
19+
// schemes:
20+
// - http
21+
// - https
22+
//
23+
// responses:
24+
// 200:
25+
// description: {{ .Title }}s
26+
// schema:
27+
// $ref: '#/definitions/{{ .Type }}s'
28+
29+
// swagger:operation GET /{{ .Resource }}/{id} get{{ .Type }}
30+
//
31+
// Get {{ .Article }} {{ .Name }}
32+
//
33+
// ---
34+
// summary: Get {{ .Name }}
35+
//
36+
// tags:
37+
// - {{ .Title }}s
38+
//
39+
// consumes:
40+
// - application/json
41+
//
42+
// produces:
43+
// - application/json
44+
//
45+
// schemes:
46+
// - http
47+
// - https
48+
//
49+
// parameters:
50+
// - name: id
51+
// in: path
52+
// required: true
53+
// type: string
54+
//
55+
// responses:
56+
// 200:
57+
// description: {{ .Title }} found
58+
// schema:
59+
// $ref: '#/definitions/{{ .Type }}'
60+
// 404:
61+
// description: {{ .Title }} not found
62+
//
63+
64+
// swagger:operation POST /{{ .Resource }} create{{ .Type }}
65+
//
66+
// Create {{ .Article }} {{ .Name }}
67+
//
68+
// ---
69+
// summary: Create {{ .Name }}
70+
//
71+
// tags:
72+
// - {{ .Title }}s
73+
//
74+
// consumes:
75+
// - application/json
76+
// - application/yaml
77+
//
78+
// produces:
79+
// - application/json
80+
//
81+
// schemes:
82+
// - http
83+
// - https
84+
//
85+
// parameters:
86+
// - name: {{ .Name }}
87+
// in: body
88+
// required: true
89+
// schema:
90+
// $ref: '#/definitions/{{ .Type }}'
91+
//
92+
// responses:
93+
// 200:
94+
// description: {{ .Title }} created
95+
// schema:
96+
// $ref: '#/definitions/{{ .Type }}'
97+
// 400:
98+
// description: create error
99+
// 409:
100+
// description: duplicated {{ .Name }}
101+
102+
// swagger:operation DELETE /{{ .Resource }}/{id} delete{{ .Type }}
103+
//
104+
// Delete {{ .Article }} {{ .Name }}
105+
//
106+
// ---
107+
// summary: Delete {{ .Name }}
108+
//
109+
// tags:
110+
// - {{ .Title }}s
111+
//
112+
// produces:
113+
// - application/json
114+
//
115+
// schemes:
116+
// - http
117+
// - https
118+
//
119+
// parameters:
120+
// - name: id
121+
// in: path
122+
// required: true
123+
// type: string
124+
//
125+
// responses:
126+
// 200:
127+
// description: {{ .Title }} deleted
128+
// 404:
129+
// description: {{ .Title }} not found
130+
package {{.env.GOPACKAGE}}

0 commit comments

Comments
 (0)