Skip to content

Commit 033ea8f

Browse files
MassadMassad
authored
Merge pull request #60 from Massad/add-swagger-doc
Add swagger doc
2 parents b67c04c + effca51 commit 033ea8f

15 files changed

Lines changed: 1856 additions & 58 deletions

File tree

‎Makefile‎

Lines changed: 24 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,24 @@
1+
## RUN APPLICATION
2+
run:
3+
@echo -e "🚀 Running the application..."
4+
@go run *.go
5+
6+
## RUN TESTS
7+
test:
8+
@echo -e "🔍 Running tests..."
9+
@go test -v ./tests/*
10+
11+
## INSTALL SWAG CLI TOOL & PACKAGES
12+
install_swag:
13+
@echo -e "📥 Installing Swag CLI and dependencies..."
14+
@which swag >/dev/null 2>&1 || (echo -e "❌ Swag CLI not found! Installing now..." && go install github.com/swaggo/swag/cmd/swag@latest)
15+
@echo -e "🔄 Updating project dependencies for Swag..."
16+
@go mod tidy
17+
@go mod download
18+
@echo -e "✅ Swag installation complete!"
19+
20+
## GENERATE API DOCUMENTATION
21+
generate_docs: install_swag
22+
@echo -e "📜 Generating API documentation using Swag..."
23+
@swag init
24+
@echo -e "✅ API documentation generated successfully!"

‎README.md‎

Lines changed: 14 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -86,6 +86,20 @@ $ sh generate-certificate.sh
8686
$ go run *.go
8787
```
8888

89+
## Generate Swagger API Docs
90+
91+
```
92+
$ make generate_docs
93+
```
94+
95+
```
96+
$ make run
97+
```
98+
99+
```
100+
$ open https://localhost:9000/swagger/index.html
101+
```
102+
89103
## Building Your Application
90104

91105
```

‎controllers/article.go‎

Lines changed: 54 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -11,13 +11,23 @@ import (
1111
"github.com/gin-gonic/gin"
1212
)
1313

14-
//ArticleController ...
14+
// ArticleController ...
1515
type ArticleController struct{}
1616

1717
var articleModel = new(models.ArticleModel)
1818
var articleForm = new(forms.ArticleForm)
1919

20-
//Create ...
20+
// Create Article godoc
21+
// @Summary Create Article example
22+
// @Schemes
23+
// @Description Create Article example
24+
// @Tags Article
25+
// @Accept json
26+
// @Produce json
27+
// @Param article body forms.CreateArticleForm true "Article"
28+
// @Success 200 {object} forms.ArticleResponse
29+
// @Failure 406 {object} forms.ArticleResponse
30+
// @Router /article [post]
2131
func (ctrl ArticleController) Create(c *gin.Context) {
2232
userID := getUserID(c)
2333

@@ -38,7 +48,16 @@ func (ctrl ArticleController) Create(c *gin.Context) {
3848
c.JSON(http.StatusOK, gin.H{"message": "Article created", "id": id})
3949
}
4050

41-
//All ...
51+
// Get All Articles godoc
52+
// @Summary Get All Articles example
53+
// @Schemes
54+
// @Description Get All Articles example
55+
// @Tags Article
56+
// @Accept json
57+
// @Produce json
58+
// @Success 200 {object} models.AllArticleResponse
59+
// @Failure 406 {object} forms.ArticleResponse
60+
// @Router /articles [GET]
4261
func (ctrl ArticleController) All(c *gin.Context) {
4362
userID := getUserID(c)
4463

@@ -51,7 +70,16 @@ func (ctrl ArticleController) All(c *gin.Context) {
5170
c.JSON(http.StatusOK, gin.H{"results": results})
5271
}
5372

54-
//One ...
73+
// Get One Article godoc
74+
// @Summary Get One Article example
75+
// @Schemes
76+
// @Description One All Article example
77+
// @Tags Article
78+
// @Accept json
79+
// @Produce json
80+
// @Success 200 {object} models.OneArticleResponse
81+
// @Failure 406 {object} forms.ArticleResponse
82+
// @Router /article/{id} [GET]
5583
func (ctrl ArticleController) One(c *gin.Context) {
5684
userID := getUserID(c)
5785

@@ -72,7 +100,17 @@ func (ctrl ArticleController) One(c *gin.Context) {
72100
c.JSON(http.StatusOK, gin.H{"data": data})
73101
}
74102

75-
//Update ...
103+
// Update Article godoc
104+
// @Summary Update Article example
105+
// @Schemes
106+
// @Description Update Article example
107+
// @Tags Article
108+
// @Accept json
109+
// @Produce json
110+
// @Param article body forms.CreateArticleForm true "Article"
111+
// @Success 200 {object} models.ArticleResponse
112+
// @Failure 406 {object} forms.ArticleResponse
113+
// @Router /article/{id} [PUT]
76114
func (ctrl ArticleController) Update(c *gin.Context) {
77115
userID := getUserID(c)
78116

@@ -101,7 +139,17 @@ func (ctrl ArticleController) Update(c *gin.Context) {
101139
c.JSON(http.StatusOK, gin.H{"message": "Article updated"})
102140
}
103141

104-
//Delete ...
142+
// Delete Article godoc
143+
// @Summary Delete Article example
144+
// @Schemes
145+
// @Description Delete Article example
146+
// @Tags Article
147+
// @Accept json
148+
// @Produce json
149+
// @Success 200 {object} models.OneArticleResponse
150+
// @Success 404 {object} forms.ArticleResponse
151+
// @Failure 406 {object} forms.ArticleResponse
152+
// @Router /article/{id} [DELETE]
105153
func (ctrl ArticleController) Delete(c *gin.Context) {
106154
userID := getUserID(c)
107155

‎controllers/auth.go‎

Lines changed: 13 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -12,12 +12,12 @@ import (
1212
jwt "github.com/golang-jwt/jwt/v4"
1313
)
1414

15-
//AuthController ...
15+
// AuthController ...
1616
type AuthController struct{}
1717

1818
var authModel = new(models.AuthModel)
1919

20-
//TokenValid ...
20+
// TokenValid ...
2121
func (ctl AuthController) TokenValid(c *gin.Context) {
2222

2323
tokenAuth, err := authModel.ExtractTokenMetadata(c.Request)
@@ -38,7 +38,17 @@ func (ctl AuthController) TokenValid(c *gin.Context) {
3838
c.Set("userID", userID)
3939
}
4040

41-
//Refresh ...
41+
// Refresh Token godoc
42+
// @Summary Refresh Token example
43+
// @Schemes
44+
// @Description Refresh Token example
45+
// @Tags Auth
46+
// @Accept json
47+
// @Produce json
48+
// @Param auth body forms.Token true "Auth"
49+
// @Success 200 {object} models.AuthResponse
50+
// @Failure 406 {object} models.MessageResponse
51+
// @Router /token/refresh [POST]
4252
func (ctl AuthController) Refresh(c *gin.Context) {
4353
var tokenForm forms.Token
4454

‎controllers/user.go‎

Lines changed: 34 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -9,19 +9,29 @@ import (
99
"github.com/gin-gonic/gin"
1010
)
1111

12-
//UserController ...
12+
// UserController ...
1313
type UserController struct{}
1414

1515
var userModel = new(models.UserModel)
1616
var userForm = new(forms.UserForm)
1717

18-
//getUserID ...
18+
// getUserID ...
1919
func getUserID(c *gin.Context) (userID int64) {
2020
//MustGet returns the value for the given key if it exists, otherwise it panics.
2121
return c.MustGet("userID").(int64)
2222
}
2323

24-
//Login ...
24+
// Login User godoc
25+
// @Summary Login User example
26+
// @Schemes
27+
// @Description Login User example
28+
// @Tags User
29+
// @Accept json
30+
// @Produce json
31+
// @Param article body forms.LoginForm true "User"
32+
// @Success 200 {object} models.UserLoginResponse
33+
// @Failure 406 {object} models.MessageResponse
34+
// @Router /user/login [post]
2535
func (ctrl UserController) Login(c *gin.Context) {
2636
var loginForm forms.LoginForm
2737

@@ -40,7 +50,17 @@ func (ctrl UserController) Login(c *gin.Context) {
4050
c.JSON(http.StatusOK, gin.H{"message": "Successfully logged in", "user": user, "token": token})
4151
}
4252

43-
//Register ...
53+
// Register User godoc
54+
// @Summary Register User example
55+
// @Schemes
56+
// @Description Register User example
57+
// @Tags User
58+
// @Accept json
59+
// @Produce json
60+
// @Param article body forms.RegisterForm true "User"
61+
// @Success 200 {object} models.UserLoginResponse
62+
// @Failure 406 {object} models.MessageResponse
63+
// @Router /user/register [post]
4464
func (ctrl UserController) Register(c *gin.Context) {
4565
var registerForm forms.RegisterForm
4666

@@ -59,7 +79,16 @@ func (ctrl UserController) Register(c *gin.Context) {
5979
c.JSON(http.StatusOK, gin.H{"message": "Successfully registered", "user": user})
6080
}
6181

62-
//Logout ...
82+
// Logout User godoc
83+
// @Summary Logout User example
84+
// @Schemes
85+
// @Description Logout User example
86+
// @Tags User
87+
// @Accept json
88+
// @Produce json
89+
// @Success 200 {object} models.MessageResponse
90+
// @Failure 406 {object} models.MessageResponse
91+
// @Router /user/logout [GET]
6392
func (ctrl UserController) Logout(c *gin.Context) {
6493

6594
au, err := authModel.ExtractTokenMetadata(c.Request)

0 commit comments

Comments
 (0)