Skip to content

Commit 9be53f0

Browse files
supwrsupwr
committed
Adding swagger documentation
1 parent 3f59685 commit 9be53f0

File tree

13 files changed

+427
-53
lines changed

13 files changed

+427
-53
lines changed

‎Dockerfile‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -6,6 +6,8 @@ COPY go.mod go.sum ./
66

77
RUN go mod download
88
RUN go install github.com/cespare/reflex@latest
9+
RUN go install github.com/golang/mock/mockgen@v1.6.0
10+
RUN go install github.com/swaggo/swag/cmd/swag@v1.16.3
911

1012
COPY . .
1113

‎Makefile‎

Lines changed: 4 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -14,4 +14,7 @@ infra.stop:
1414
docker-compose stop db
1515

1616
migrate:
17-
docker run --network pismo-transactions_pismo_transactions --env-file .env pismo-transactions-app go run /app/cmd/.
17+
docker-compose run app go run /app/cmd/.
18+
19+
swagger:
20+
docker-compose run app swag init -d /app/api/

‎api/api.go‎

Lines changed: 0 additions & 37 deletions
This file was deleted.

‎api/fx.go‎

Lines changed: 0 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -18,7 +18,6 @@ func createApp(o ...fx.Option) *fx.App {
1818
newConfig,
1919
newLogger,
2020
newConnection,
21-
newApi,
2221
newAccountHandler,
2322
newAccountService,
2423

@@ -49,10 +48,6 @@ func newAccountHandler(s *account.Service, l *slog.Logger) *handler.AccountHandl
4948
return handler.NewAccountHandler(s, l)
5049
}
5150

52-
func newApi(args ApiArgs) *Api {
53-
return NewApi(args)
54-
}
55-
5651
func newAccountService(r account.RepositoryInterface) *account.Service {
5752
return account.NewService(r)
5853
}

‎api/handler/account.go‎

Lines changed: 26 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -10,6 +10,10 @@ import (
1010
"strconv"
1111
)
1212

13+
type AccountInputDTO struct {
14+
DocumentNumber entity.Document `json:"document_number" swaggertype:"string" validate:"required"`
15+
}
16+
1317
type AccountHandler struct {
1418
AccountService *account.Service
1519
logger *slog.Logger
@@ -22,11 +26,20 @@ func NewAccountHandler(service *account.Service, logger *slog.Logger) *AccountHa
2226
}
2327
}
2428

29+
// CreateAccount godoc
30+
// @Summary Create account
31+
// @Description Add new account
32+
// @Tags Accounts
33+
// @Accept json
34+
// @Produce json
35+
// @Param request body AccountInputDTO true "Account properties"
36+
// @Success 201
37+
// @Failure 500
38+
// @Failure 400
39+
// @Router /accounts [post]
2540
func (h *AccountHandler) CreateAccount(ctx *gin.Context) {
2641
var err error
27-
var input struct {
28-
DocumentNumber entity.Document `json:"document_number" validate:"required"`
29-
}
42+
var input AccountInputDTO
3043

3144
if err = ctx.BindJSON(&input); err != nil {
3245
h.logger.Error("error reading body", slog.Any("error", err))
@@ -62,6 +75,16 @@ func (h *AccountHandler) CreateAccount(ctx *gin.Context) {
6275
return
6376
}
6477

78+
// GetAccountById godoc
79+
// @Summary Show account details
80+
// @Description Get account by id
81+
// @Tags Accounts
82+
// @Produce json
83+
// @Param accountId path integer true "Account id"
84+
// @Success 200
85+
// @Failure 500
86+
// @Failure 404
87+
// @Router /accounts/{accountId} [get]
6588
func (h *AccountHandler) GetAccountById(ctx *gin.Context) {
6689
id, err := strconv.Atoi(ctx.Param("accountId"))
6790
if err != nil {

‎api/handler/errors.go‎

Lines changed: 0 additions & 5 deletions
This file was deleted.

‎api/handler/handler.go‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,10 +1,13 @@
11
package handler
22

33
import (
4+
"errors"
45
"github.com/go-playground/validator/v10"
56
"strings"
67
)
78

9+
var ErrCreateAccount = errors.New("Error creating account")
10+
811
type Validation struct {
912
Errors []Field
1013
}

‎api/main.go‎

Lines changed: 16 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,16 +1,30 @@
11
package main
22

33
import (
4+
"github.com/gin-gonic/gin"
45
"github.com/shopspring/decimal"
6+
"github.com/supwr/pismo-transactions/api/handler"
7+
_ "github.com/supwr/pismo-transactions/docs"
8+
swaggerFiles "github.com/swaggo/files"
9+
"github.com/swaggo/gin-swagger"
510
"go.uber.org/fx"
611
)
712

13+
// @title Transactions API
14+
// @version 1.0
815
func main() {
916
decimal.MarshalJSONWithoutQuotes = true
1017

1118
app := createApp(
12-
fx.Invoke(func(api *Api) {
13-
api.Serve()
19+
fx.Invoke(func(accountHandler *handler.AccountHandler) {
20+
api := gin.Default()
21+
22+
// routes
23+
api.GET("/accounts/:accountId", accountHandler.GetAccountById)
24+
api.POST("/accounts", accountHandler.CreateAccount)
25+
api.GET("/docs/*any", ginSwagger.WrapHandler(swaggerFiles.Handler))
26+
27+
api.Run()
1428
}),
1529
fx.Invoke(func(s fx.Shutdowner) { _ = s.Shutdown() }),
1630
)

‎docs/docs.go‎

Lines changed: 119 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,119 @@
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+
"/accounts": {
19+
"post": {
20+
"description": "Add new account",
21+
"consumes": [
22+
"application/json"
23+
],
24+
"produces": [
25+
"application/json"
26+
],
27+
"tags": [
28+
"Accounts"
29+
],
30+
"summary": "Create account",
31+
"parameters": [
32+
{
33+
"description": "Account properties",
34+
"name": "request",
35+
"in": "body",
36+
"required": true,
37+
"schema": {
38+
"$ref": "#/definitions/handler.AccountInputDTO"
39+
}
40+
}
41+
],
42+
"responses": {
43+
"201": {
44+
"description": "Created"
45+
},
46+
"400": {
47+
"description": "Bad Request"
48+
},
49+
"500": {
50+
"description": "Internal Server Error"
51+
}
52+
}
53+
}
54+
},
55+
"/accounts/{accountId}": {
56+
"get": {
57+
"description": "Get account by id",
58+
"produces": [
59+
"application/json"
60+
],
61+
"tags": [
62+
"Accounts"
63+
],
64+
"summary": "Show account details",
65+
"parameters": [
66+
{
67+
"type": "integer",
68+
"description": "Account id",
69+
"name": "accountId",
70+
"in": "path",
71+
"required": true
72+
}
73+
],
74+
"responses": {
75+
"200": {
76+
"description": "OK"
77+
},
78+
"404": {
79+
"description": "Not Found"
80+
},
81+
"500": {
82+
"description": "Internal Server Error"
83+
}
84+
}
85+
}
86+
}
87+
},
88+
"definitions": {
89+
"handler.AccountInputDTO": {
90+
"type": "object",
91+
"required": [
92+
"document_number"
93+
],
94+
"properties": {
95+
"document_number": {
96+
"type": "string"
97+
}
98+
}
99+
}
100+
}
101+
}`
102+
103+
// SwaggerInfo holds exported Swagger Info so clients can modify it
104+
var SwaggerInfo = &swag.Spec{
105+
Version: "1.0",
106+
Host: "",
107+
BasePath: "",
108+
Schemes: []string{},
109+
Title: "Transactions API",
110+
Description: "",
111+
InfoInstanceName: "swagger",
112+
SwaggerTemplate: docTemplate,
113+
LeftDelim: "{{",
114+
RightDelim: "}}",
115+
}
116+
117+
func init() {
118+
swag.Register(SwaggerInfo.InstanceName(), SwaggerInfo)
119+
}

‎docs/swagger.json‎

Lines changed: 92 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,92 @@
1+
{
2+
"swagger": "2.0",
3+
"info": {
4+
"title": "Transactions API",
5+
"contact": {},
6+
"version": "1.0"
7+
},
8+
"paths": {
9+
"/accounts": {
10+
"post": {
11+
"description": "Add new account",
12+
"consumes": [
13+
"application/json"
14+
],
15+
"produces": [
16+
"application/json"
17+
],
18+
"tags": [
19+
"Accounts"
20+
],
21+
"summary": "Create account",
22+
"parameters": [
23+
{
24+
"description": "Account properties",
25+
"name": "request",
26+
"in": "body",
27+
"required": true,
28+
"schema": {
29+
"$ref": "#/definitions/handler.AccountInputDTO"
30+
}
31+
}
32+
],
33+
"responses": {
34+
"201": {
35+
"description": "Created"
36+
},
37+
"400": {
38+
"description": "Bad Request"
39+
},
40+
"500": {
41+
"description": "Internal Server Error"
42+
}
43+
}
44+
}
45+
},
46+
"/accounts/{accountId}": {
47+
"get": {
48+
"description": "Get account by id",
49+
"produces": [
50+
"application/json"
51+
],
52+
"tags": [
53+
"Accounts"
54+
],
55+
"summary": "Show account details",
56+
"parameters": [
57+
{
58+
"type": "integer",
59+
"description": "Account id",
60+
"name": "accountId",
61+
"in": "path",
62+
"required": true
63+
}
64+
],
65+
"responses": {
66+
"200": {
67+
"description": "OK"
68+
},
69+
"404": {
70+
"description": "Not Found"
71+
},
72+
"500": {
73+
"description": "Internal Server Error"
74+
}
75+
}
76+
}
77+
}
78+
},
79+
"definitions": {
80+
"handler.AccountInputDTO": {
81+
"type": "object",
82+
"required": [
83+
"document_number"
84+
],
85+
"properties": {
86+
"document_number": {
87+
"type": "string"
88+
}
89+
}
90+
}
91+
}
92+
}

0 commit comments

Comments
 (0)