Skip to content

Commit 3710a4f

Browse files
verbotenjverbotenj
committed
feat: swagger using swaggo/swag and gin-swagger
Signed-off-by: Ales Verbic <[email protected]>
1 parent 15c1da9 commit 3710a4f

File tree

8 files changed

+582
-15
lines changed

8 files changed

+582
-15
lines changed

‎Makefile‎

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -25,6 +25,13 @@ mod-tidy:
2525
clean:
2626
rm -f $(BINARIES)
2727

28+
format: mod-tidy
29+
go fmt ./...
30+
31+
swagger:
32+
swag f -g api.go -d api,output
33+
swag i -g api.go -d api,output
34+
2835
test: mod-tidy
2936
go test -v ./...
3037

‎api/api.go‎

Lines changed: 16 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -6,7 +6,10 @@ import (
66
"sync"
77
"time"
88

9+
_ "github.com/blinklabs-io/snek/docs"
910
"github.com/gin-gonic/gin"
11+
swaggerFiles "github.com/swaggo/files" // swagger embed files
12+
ginSwagger "github.com/swaggo/gin-swagger" // gin-swagger middleware
1013
)
1114

1215
type API interface {
@@ -71,6 +74,18 @@ func (a *APIv1) Engine() *gin.Engine {
7174
return a.engine
7275
}
7376

77+
// @title Snek API
78+
// @version v1
79+
// @description Snek API
80+
// @Schemes http
81+
// @BasePath /v1
82+
83+
// @contact.name Blink Labs
84+
// @contact.url https://blinklabs.io
85+
// @contact.email [email protected]
86+
87+
// @license.name Apache 2.0
88+
// @license.url http://www.apache.org/licenses/LICENSE-2.0.html
7489
func (a *APIv1) Start() error {
7590
address := a.host + ":" + a.port
7691
// Use buffered channel to not block goroutine
@@ -140,8 +155,7 @@ func ConfigureRouter(debug bool) *gin.Engine {
140155
c.String(200, "pong")
141156
})
142157
// Swagger UI
143-
// TODO: add swagger UI
144-
// g.Static("/swagger-ui", "swagger-ui")
158+
g.GET("/swagger/*any", ginSwagger.WrapHandler(swaggerFiles.Handler))
145159
return g
146160
}
147161

‎docs/docs.go‎

Lines changed: 177 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,177 @@
1+
// Package docs Code generated by swaggo/swag. DO NOT EDIT
2+
package docs
3+
4+
import "github.com/swaggo/swag"
5+
6+
const docTemplate = `{
7+
"schemes": {{ marshal .Schemes }},
8+
"swagger": "2.0",
9+
"info": {
10+
"description": "{{escape .Description}}",
11+
"title": "{{.Title}}",
12+
"contact": {
13+
"name": "Blink Labs",
14+
"url": "https://blinklabs.io",
15+
"email": "[email protected]"
16+
},
17+
"license": {
18+
"name": "Apache 2.0",
19+
"url": "http://www.apache.org/licenses/LICENSE-2.0.html"
20+
},
21+
"version": "{{.Version}}"
22+
},
23+
"host": "{{.Host}}",
24+
"basePath": "{{.BasePath}}",
25+
"paths": {
26+
"/fcm": {
27+
"post": {
28+
"description": "Store a new FCM token",
29+
"consumes": [
30+
"application/json"
31+
],
32+
"produces": [
33+
"application/json"
34+
],
35+
"summary": "Store FCM Token",
36+
"parameters": [
37+
{
38+
"description": "FCM Token Request",
39+
"name": "body",
40+
"in": "body",
41+
"required": true,
42+
"schema": {
43+
"$ref": "#/definitions/push.TokenRequest"
44+
}
45+
}
46+
],
47+
"responses": {
48+
"201": {
49+
"description": "Created",
50+
"schema": {
51+
"type": "string"
52+
}
53+
},
54+
"400": {
55+
"description": "Bad Request",
56+
"schema": {
57+
"$ref": "#/definitions/push.ErrorResponse"
58+
}
59+
}
60+
}
61+
}
62+
},
63+
"/fcm/{token}": {
64+
"get": {
65+
"description": "Get an FCM token by its value",
66+
"consumes": [
67+
"application/json"
68+
],
69+
"produces": [
70+
"application/json"
71+
],
72+
"summary": "Get FCM Token",
73+
"parameters": [
74+
{
75+
"type": "string",
76+
"description": "FCM Token",
77+
"name": "token",
78+
"in": "path",
79+
"required": true
80+
}
81+
],
82+
"responses": {
83+
"200": {
84+
"description": "OK",
85+
"schema": {
86+
"$ref": "#/definitions/push.TokenResponse"
87+
}
88+
},
89+
"404": {
90+
"description": "Not Found",
91+
"schema": {
92+
"$ref": "#/definitions/push.ErrorResponse"
93+
}
94+
}
95+
}
96+
},
97+
"delete": {
98+
"description": "Delete an FCM token by its value",
99+
"consumes": [
100+
"application/json"
101+
],
102+
"produces": [
103+
"application/json"
104+
],
105+
"summary": "Delete FCM Token",
106+
"parameters": [
107+
{
108+
"type": "string",
109+
"description": "FCM Token",
110+
"name": "token",
111+
"in": "path",
112+
"required": true
113+
}
114+
],
115+
"responses": {
116+
"204": {
117+
"description": "No Content",
118+
"schema": {
119+
"type": "string"
120+
}
121+
},
122+
"404": {
123+
"description": "Not Found",
124+
"schema": {
125+
"$ref": "#/definitions/push.ErrorResponse"
126+
}
127+
}
128+
}
129+
}
130+
}
131+
},
132+
"definitions": {
133+
"push.ErrorResponse": {
134+
"type": "object",
135+
"properties": {
136+
"error": {
137+
"type": "string"
138+
}
139+
}
140+
},
141+
"push.TokenRequest": {
142+
"type": "object",
143+
"required": [
144+
"fcmToken"
145+
],
146+
"properties": {
147+
"fcmToken": {
148+
"type": "string"
149+
}
150+
}
151+
},
152+
"push.TokenResponse": {
153+
"type": "object",
154+
"properties": {
155+
"fcmToken": {
156+
"type": "string"
157+
}
158+
}
159+
}
160+
}
161+
}`
162+
163+
// SwaggerInfo holds exported Swagger Info so clients can modify it
164+
var SwaggerInfo = &swag.Spec{
165+
Version: "v1",
166+
Host: "",
167+
BasePath: "/v1",
168+
Schemes: []string{"http"},
169+
Title: "Snek API",
170+
Description: "Snek API",
171+
InfoInstanceName: "swagger",
172+
SwaggerTemplate: docTemplate,
173+
}
174+
175+
func init() {
176+
swag.Register(SwaggerInfo.InstanceName(), SwaggerInfo)
177+
}

‎docs/swagger.json‎

Lines changed: 157 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,157 @@
1+
{
2+
"schemes": [
3+
"http"
4+
],
5+
"swagger": "2.0",
6+
"info": {
7+
"description": "Snek API",
8+
"title": "Snek API",
9+
"contact": {
10+
"name": "Blink Labs",
11+
"url": "https://blinklabs.io",
12+
"email": "[email protected]"
13+
},
14+
"license": {
15+
"name": "Apache 2.0",
16+
"url": "http://www.apache.org/licenses/LICENSE-2.0.html"
17+
},
18+
"version": "v1"
19+
},
20+
"basePath": "/v1",
21+
"paths": {
22+
"/fcm": {
23+
"post": {
24+
"description": "Store a new FCM token",
25+
"consumes": [
26+
"application/json"
27+
],
28+
"produces": [
29+
"application/json"
30+
],
31+
"summary": "Store FCM Token",
32+
"parameters": [
33+
{
34+
"description": "FCM Token Request",
35+
"name": "body",
36+
"in": "body",
37+
"required": true,
38+
"schema": {
39+
"$ref": "#/definitions/push.TokenRequest"
40+
}
41+
}
42+
],
43+
"responses": {
44+
"201": {
45+
"description": "Created",
46+
"schema": {
47+
"type": "string"
48+
}
49+
},
50+
"400": {
51+
"description": "Bad Request",
52+
"schema": {
53+
"$ref": "#/definitions/push.ErrorResponse"
54+
}
55+
}
56+
}
57+
}
58+
},
59+
"/fcm/{token}": {
60+
"get": {
61+
"description": "Get an FCM token by its value",
62+
"consumes": [
63+
"application/json"
64+
],
65+
"produces": [
66+
"application/json"
67+
],
68+
"summary": "Get FCM Token",
69+
"parameters": [
70+
{
71+
"type": "string",
72+
"description": "FCM Token",
73+
"name": "token",
74+
"in": "path",
75+
"required": true
76+
}
77+
],
78+
"responses": {
79+
"200": {
80+
"description": "OK",
81+
"schema": {
82+
"$ref": "#/definitions/push.TokenResponse"
83+
}
84+
},
85+
"404": {
86+
"description": "Not Found",
87+
"schema": {
88+
"$ref": "#/definitions/push.ErrorResponse"
89+
}
90+
}
91+
}
92+
},
93+
"delete": {
94+
"description": "Delete an FCM token by its value",
95+
"consumes": [
96+
"application/json"
97+
],
98+
"produces": [
99+
"application/json"
100+
],
101+
"summary": "Delete FCM Token",
102+
"parameters": [
103+
{
104+
"type": "string",
105+
"description": "FCM Token",
106+
"name": "token",
107+
"in": "path",
108+
"required": true
109+
}
110+
],
111+
"responses": {
112+
"204": {
113+
"description": "No Content",
114+
"schema": {
115+
"type": "string"
116+
}
117+
},
118+
"404": {
119+
"description": "Not Found",
120+
"schema": {
121+
"$ref": "#/definitions/push.ErrorResponse"
122+
}
123+
}
124+
}
125+
}
126+
}
127+
},
128+
"definitions": {
129+
"push.ErrorResponse": {
130+
"type": "object",
131+
"properties": {
132+
"error": {
133+
"type": "string"
134+
}
135+
}
136+
},
137+
"push.TokenRequest": {
138+
"type": "object",
139+
"required": [
140+
"fcmToken"
141+
],
142+
"properties": {
143+
"fcmToken": {
144+
"type": "string"
145+
}
146+
}
147+
},
148+
"push.TokenResponse": {
149+
"type": "object",
150+
"properties": {
151+
"fcmToken": {
152+
"type": "string"
153+
}
154+
}
155+
}
156+
}
157+
}

0 commit comments

Comments
 (0)