Skip to content

Commit 06b0934

Browse files
author
Armin
committed
add Swagger documentation for balance and SMS endpoints, including request and response models
1 parent 3530d6b commit 06b0934

File tree

8 files changed

+469
-48
lines changed

8 files changed

+469
-48
lines changed

‎cmd/api/main.go‎

Lines changed: 12 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -7,15 +7,23 @@ import (
77
"sms-gateway/internal/balance"
88
"sms-gateway/internal/sms"
99

10+
_ "sms-gateway/docs"
11+
1012
"github.com/rabbitmq/amqp091-go"
13+
echSwagger "github.com/swaggo/echo-swagger"
1114
)
1215

16+
// @title SMS Gateway API
17+
// @version 1.0
18+
// @description Simple SMS gateway with balance management and operator failover.
19+
// @host localhost:8080
20+
// @BasePath /
1321
func main() {
1422
app.Init()
1523

1624
CreateHermesAndIVRQueue()
1725

18-
// Consumers
26+
// Consumers
1927
if err := sms.StartConsumers(context.Background()); err != nil {
2028
panic(err)
2129
}
@@ -29,6 +37,9 @@ func main() {
2937
app.Echo.GET("/balance", balance.GetBalanceAndHistoryHandler)
3038
app.Echo.POST("/balance/add", balance.AddBalanceHandler)
3139

40+
// swagger
41+
app.Echo.GET("/swagger/*", echSwagger.WrapHandler)
42+
3243
if err := app.Echo.Start(config.AppListenAddr); err != nil {
3344
panic(err)
3445
}

‎docs/docs.go‎

Lines changed: 288 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,288 @@
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+
"version": "{{.Version}}"
14+
},
15+
"host": "{{.Host}}",
16+
"basePath": "{{.BasePath}}",
17+
"paths": {
18+
"/balance": {
19+
"get": {
20+
"description": "Returns current balance and transaction history",
21+
"produces": [
22+
"application/json"
23+
],
24+
"tags": [
25+
"balance"
26+
],
27+
"summary": "Get user balance and transactions",
28+
"parameters": [
29+
{
30+
"type": "string",
31+
"description": "User ID",
32+
"name": "user_id",
33+
"in": "query",
34+
"required": true
35+
}
36+
],
37+
"responses": {
38+
"200": {
39+
"description": "OK",
40+
"schema": {
41+
"type": "object",
42+
"additionalProperties": true
43+
}
44+
},
45+
"400": {
46+
"description": "user_id is required",
47+
"schema": {
48+
"type": "string"
49+
}
50+
},
51+
"500": {
52+
"description": "internal error",
53+
"schema": {
54+
"type": "string"
55+
}
56+
}
57+
}
58+
}
59+
},
60+
"/balance/add": {
61+
"post": {
62+
"description": "Increases user balance and records transaction",
63+
"consumes": [
64+
"application/json"
65+
],
66+
"produces": [
67+
"application/json"
68+
],
69+
"tags": [
70+
"balance"
71+
],
72+
"summary": "Add balance for user",
73+
"parameters": [
74+
{
75+
"description": "Add balance request",
76+
"name": "request",
77+
"in": "body",
78+
"required": true,
79+
"schema": {
80+
"$ref": "#/definitions/balance.AddBalancePayload"
81+
}
82+
}
83+
],
84+
"responses": {
85+
"200": {
86+
"description": "done",
87+
"schema": {
88+
"type": "string"
89+
}
90+
},
91+
"400": {
92+
"description": "invalid input",
93+
"schema": {
94+
"type": "string"
95+
}
96+
},
97+
"500": {
98+
"description": "internal error",
99+
"schema": {
100+
"type": "string"
101+
}
102+
}
103+
}
104+
}
105+
},
106+
"/sms/history": {
107+
"get": {
108+
"description": "Returns sent SMS history for a user",
109+
"consumes": [
110+
"application/json"
111+
],
112+
"produces": [
113+
"application/json"
114+
],
115+
"tags": [
116+
"sms"
117+
],
118+
"summary": "Get SMS history for user",
119+
"parameters": [
120+
{
121+
"type": "string",
122+
"description": "User ID",
123+
"name": "user_id",
124+
"in": "query",
125+
"required": true
126+
},
127+
{
128+
"type": "string",
129+
"description": "Filter by status (init|done|failed)",
130+
"name": "status",
131+
"in": "query"
132+
},
133+
{
134+
"type": "string",
135+
"description": "Filter by sms_identifier",
136+
"name": "sms_identifier",
137+
"in": "query"
138+
}
139+
],
140+
"responses": {
141+
"200": {
142+
"description": "OK",
143+
"schema": {
144+
"type": "object",
145+
"additionalProperties": true
146+
}
147+
},
148+
"400": {
149+
"description": "user_id is required",
150+
"schema": {
151+
"type": "string"
152+
}
153+
},
154+
"500": {
155+
"description": "internal error",
156+
"schema": {
157+
"type": "string"
158+
}
159+
}
160+
}
161+
}
162+
},
163+
"/sms/send": {
164+
"post": {
165+
"description": "Deducts balance, enqueues SMS for processing, returns processing ack",
166+
"consumes": [
167+
"application/json"
168+
],
169+
"produces": [
170+
"application/json"
171+
],
172+
"tags": [
173+
"sms"
174+
],
175+
"summary": "Send SMS request",
176+
"parameters": [
177+
{
178+
"description": "SMS request",
179+
"name": "request",
180+
"in": "body",
181+
"required": true,
182+
"schema": {
183+
"$ref": "#/definitions/model.SMS"
184+
}
185+
}
186+
],
187+
"responses": {
188+
"200": {
189+
"description": "ack with sms_identifier",
190+
"schema": {
191+
"type": "object",
192+
"additionalProperties": true
193+
}
194+
},
195+
"400": {
196+
"description": "invalid input",
197+
"schema": {
198+
"type": "string"
199+
}
200+
},
201+
"402": {
202+
"description": "dont have Not Enough Balance",
203+
"schema": {
204+
"type": "string"
205+
}
206+
},
207+
"500": {
208+
"description": "internal error",
209+
"schema": {
210+
"type": "string"
211+
}
212+
}
213+
}
214+
}
215+
}
216+
},
217+
"definitions": {
218+
"balance.AddBalancePayload": {
219+
"type": "object",
220+
"properties": {
221+
"balance": {
222+
"type": "integer"
223+
},
224+
"description": {
225+
"type": "string"
226+
},
227+
"user_id": {
228+
"type": "integer"
229+
}
230+
}
231+
},
232+
"model.SMS": {
233+
"type": "object",
234+
"properties": {
235+
"customer_id": {
236+
"type": "integer"
237+
},
238+
"recipients": {
239+
"type": "array",
240+
"items": {
241+
"type": "string"
242+
}
243+
},
244+
"sms_identifier": {
245+
"type": "string"
246+
},
247+
"text": {
248+
"type": "string"
249+
},
250+
"transaction_id": {
251+
"type": "string"
252+
},
253+
"type": {
254+
"$ref": "#/definitions/model.Type"
255+
}
256+
}
257+
},
258+
"model.Type": {
259+
"type": "string",
260+
"enum": [
261+
"normal",
262+
"express"
263+
],
264+
"x-enum-varnames": [
265+
"NORMAL",
266+
"EXPRESS"
267+
]
268+
}
269+
}
270+
}`
271+
272+
// SwaggerInfo holds exported Swagger Info so clients can modify it
273+
var SwaggerInfo = &swag.Spec{
274+
Version: "1.0",
275+
Host: "localhost:8080",
276+
BasePath: "/",
277+
Schemes: []string{},
278+
Title: "SMS Gateway API For Arvan ",
279+
Description: "Simple SMS gateway with balance management and operator failover.",
280+
InfoInstanceName: "swagger",
281+
SwaggerTemplate: docTemplate,
282+
LeftDelim: "{{",
283+
RightDelim: "}}",
284+
}
285+
286+
func init() {
287+
swag.Register(SwaggerInfo.InstanceName(), SwaggerInfo)
288+
}

‎go.mod‎

Lines changed: 15 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -9,17 +9,32 @@ require (
99
github.com/joho/godotenv v1.5.1
1010
github.com/labstack/echo/v4 v4.14.0
1111
github.com/rabbitmq/amqp091-go v1.10.0
12+
github.com/swaggo/echo-swagger v1.4.1
13+
github.com/swaggo/swag v1.16.3
1214
)
1315

1416
require (
1517
filippo.io/edwards25519 v1.1.0 // indirect
18+
github.com/KyleBanks/depth v1.2.1 // indirect
19+
github.com/PuerkitoBio/purell v1.1.1 // indirect
20+
github.com/PuerkitoBio/urlesc v0.0.0-20170810143723-de5bf2ad4578 // indirect
21+
github.com/ghodss/yaml v1.0.0 // indirect
22+
github.com/go-openapi/jsonpointer v0.19.5 // indirect
23+
github.com/go-openapi/jsonreference v0.19.6 // indirect
24+
github.com/go-openapi/spec v0.20.4 // indirect
25+
github.com/go-openapi/swag v0.19.15 // indirect
26+
github.com/josharian/intern v1.0.0 // indirect
1627
github.com/labstack/gommon v0.4.2 // indirect
28+
github.com/mailru/easyjson v0.7.7 // indirect
1729
github.com/mattn/go-colorable v0.1.14 // indirect
1830
github.com/mattn/go-isatty v0.0.20 // indirect
31+
github.com/swaggo/files/v2 v2.0.0 // indirect
1932
github.com/valyala/bytebufferpool v1.0.0 // indirect
2033
github.com/valyala/fasttemplate v1.2.2 // indirect
2134
golang.org/x/crypto v0.46.0 // indirect
2235
golang.org/x/net v0.48.0 // indirect
2336
golang.org/x/sys v0.39.0 // indirect
2437
golang.org/x/text v0.32.0 // indirect
38+
golang.org/x/tools v0.39.0 // indirect
39+
gopkg.in/yaml.v2 v2.4.0 // indirect
2540
)

0 commit comments

Comments
 (0)