Skip to content

Commit a2fc93c

Browse files
KunalKumar-1KunalKumar-1
authored
Merge pull request #8 from KunalKumar-1/swagger
docs: added swagger docs
2 parents 841a9d0 + d3eb219 commit a2fc93c

File tree

9 files changed

+1359
-30
lines changed

9 files changed

+1359
-30
lines changed

‎README.md‎

Lines changed: 39 additions & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -100,18 +100,47 @@ make clean
100100

101101
## Project Structure
102102
```
103-
.
104103
├── cmd/
105-
│ ├── api/ # Main API application
106-
│ └── migrate/ # Database migrations
104+
│ ├── api/ # Main API application (Gin server)
105+
│ │ ├── auth.go # Authentication handlers (login, register)
106+
│ │ ├── contex.go # Helper functions to get user from context
107+
│ │ ├── events.go # Event CRUD handlers
108+
│ │ ├── main.go # Entry point for API server
109+
│ │ ├── middleware.go # Authentication & logging middleware
110+
│ │ ├── routes.go # Route definitions
111+
│ │ └── server.go # Server configuration & startup
112+
│ └── migrate/ # Database migrations
113+
│ └── migrations/
114+
│ ├── 000001_create_user_table.up.sql
115+
│ ├── 000001_create_user_table.down.sql
116+
│ ├── 000002_create_events_table.up.sql
117+
│ ├── 000002_create_events_table.down.sql
118+
│ ├── 000003_create_attendance_table.up.sql
119+
│ ├── 000003_create_attendance_table.down.sql
120+
│ └── main.go
121+
│
107122
├── internals/
108-
│ ├── database/ # Database models and queries
109-
│ └── env/ # Environment configuration
110-
├── server/ # Server configurations
111-
├── Makefile # Build automation
112-
├── data.db # SQLite database
113-
├── .air.toml # Air configuration
114-
└── go.mod # Go modules
123+
│ ├── database/ # Database models and queries
124+
│ │ ├── models.go # Model registry
125+
│ │ ├── users.go # User model & queries
126+
│ │ ├── event.go # Event model & queries
127+
│ │ └── attendee.go # Attendance model & queries
128+
│ └── env/ # Environment configuration (env variables)
129+
│ └── env.go
130+
│
131+
├── server/ # Server-related files (local data, configs)
132+
│ └── data.db # Local SQLite database
133+
│
134+
├── tmp/ # Temporary build and runtime files
135+
│ ├── main # Compiled binary (generated by Air)
136+
│ └── build-errors.log # Logs from failed builds
137+
│
138+
├── Makefile # Build & run automation commands
139+
├── go.mod # Go module definition
140+
├── go.sum # Dependency checksums
141+
├── data.db # Development SQLite database
142+
├── .air.toml # Air live-reload configuration
143+
└── README.md # Project documentation
115144
```
116145

117146
## API Endpoints

‎cmd/api/events.go‎

Lines changed: 78 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -9,7 +9,18 @@ import (
99
"github.com/kunalkumar-1/Evently/internals/database"
1010
)
1111

12-
// create event handler
12+
// CreateEvent creates a new event
13+
// @Summary Create a new event
14+
// @Description Create a new event owned by the authenticated user
15+
// @Tags Events
16+
// @Accept json
17+
// @Produce json
18+
// @Param event body database.Event true "Event Data"
19+
// @Success 201 {object} database.Event
20+
// @Failure 400 {object} map[string]string
21+
// @Failure 500 {object} map[string]string
22+
// @Router /events [post]
23+
// @Security BearerAuth
1324
func (app *application) createEvent(c *gin.Context) {
1425

1526
var event database.Event
@@ -39,7 +50,16 @@ func (app *application) createEvent(c *gin.Context) {
3950
c.JSON(http.StatusCreated, event)
4051
}
4152

42-
// get all events
53+
// GetAllEvent returns all events
54+
// @Summary Get all events
55+
// @Description Retrieve a list of all available events
56+
// @Tags Events
57+
// @Accept json
58+
// @Produce json
59+
// @Success 200 {array} database.Event
60+
// @Failure 500 {object} map[string]string "Failed to retrieve events"
61+
// @Router /events [get]
62+
4363
func (app *application) getAllEvent(c *gin.Context) {
4464
events, err := app.models.Events.GetAll()
4565
if err != nil {
@@ -51,7 +71,17 @@ func (app *application) getAllEvent(c *gin.Context) {
5171
c.JSON(http.StatusOK, events)
5272
}
5373

54-
// get events
74+
// GetEvent retrieves an event by ID
75+
// @Summary Get event by ID
76+
// @Description Retrieve details of a specific event
77+
// @Tags Events
78+
// @Accept json
79+
// @Produce json
80+
// @Param id path int true "Event ID"
81+
// @Success 200 {object} database.Event
82+
// @Failure 400 {object} map[string]string
83+
// @Failure 404 {object} map[string]string
84+
// @Router /events/{id} [get]
5585
func (app *application) getEvent(c *gin.Context) {
5686
id, err := strconv.Atoi(c.Param("id"))
5787
if err != nil {
@@ -78,7 +108,20 @@ func (app *application) getEvent(c *gin.Context) {
78108
c.JSON(http.StatusCreated, event)
79109
}
80110

81-
// update event
111+
// UpdateEvent updates an existing event
112+
// @Summary Update event
113+
// @Description Update an existing event by ID (only by owner)
114+
// @Tags Events
115+
// @Accept json
116+
// @Produce json
117+
// @Param id path int true "Event ID"
118+
// @Param event body database.Event true "Updated Event Data"
119+
// @Success 200 {object} database.Event
120+
// @Failure 400 {object} map[string]string
121+
// @Failure 403 {object} map[string]string
122+
// @Failure 500 {object} map[string]string
123+
// @Router /events/{id} [put]
124+
// @Security BearerAuth
82125
func (app *application) updateEvent(c *gin.Context) {
83126
id, err := strconv.Atoi(c.Param("id")) // get event id from url
84127
if err != nil {
@@ -137,7 +180,17 @@ func (app *application) updateEvent(c *gin.Context) {
137180
c.JSON(http.StatusOK, updatedEvent)
138181
}
139182

140-
// delete event
183+
// DeleteEvent deletes an event by ID
184+
// @Summary Delete event
185+
// @Description Delete an event by ID (only by owner)
186+
// @Tags Events
187+
// @Param id path int true "Event ID"
188+
// @Success 204 {object} nil
189+
// @Failure 400 {object} map[string]string
190+
// @Failure 403 {object} map[string]string
191+
// @Failure 404 {object} map[string]string
192+
// @Router /events/{id} [delete]
193+
// @Security BearerAuth
141194
func (app *application) deleteEvent(c *gin.Context) {
142195
id, err := strconv.Atoi(c.Param("id"))
143196
if err != nil {
@@ -178,6 +231,18 @@ func (app *application) deleteEvent(c *gin.Context) {
178231

179232
}
180233

234+
// AddAttendeeToEvent adds a user to an event
235+
// @Summary Add attendee to event
236+
// @Description Adds a user as an attendee to a specific event
237+
// @Tags Attendees
238+
// @Param id path int true "Event ID"
239+
// @Param userId path int true "User ID"
240+
// @Success 201 {object} database.Attendee
241+
// @Failure 400 {object} map[string]string
242+
// @Failure 403 {object} map[string]string
243+
// @Failure 404 {object} map[string]string
244+
// @Router /events/{id}/attendees/{userId} [post]
245+
// @Security BearerAuth
181246
func (app *application) addAttendeeToEvent(c *gin.Context) {
182247
eventId, err := strconv.Atoi(c.Param("id"))
183248
if err != nil {
@@ -262,6 +327,14 @@ func (app *application) addAttendeeToEvent(c *gin.Context) {
262327
c.JSON(http.StatusCreated, attendee)
263328
}
264329

330+
// GetAttendeesForEvent retrieves attendees for a given event
331+
// @Summary Get attendees for event
332+
// @Description Get a list of all attendees for a specific event
333+
// @Tags Attendees
334+
// @Param id path int true "Event ID"
335+
// @Success 200 {array} database.Attendee
336+
// @Failure 400 {object} map[string]string
337+
// @Router /events/{id}/attendees [get]
265338
func (app *application) getAttendeesForEvent(c *gin.Context) {
266339
id, err := strconv.Atoi(c.Param("id"))
267340
if err != nil {

‎cmd/api/main.go‎

Lines changed: 16 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -5,11 +5,27 @@ import (
55
"log"
66

77
_ "github.com/joho/godotenv/autoload"
8+
_ "github.com/kunalkumar-1/Evently/docs"
89
"github.com/kunalkumar-1/Evently/internals/database"
910
"github.com/kunalkumar-1/Evently/internals/env"
1011
_ "github.com/mattn/go-sqlite3"
1112
)
1213

14+
// @title Evently API
15+
// @version 1.0
16+
// @description Event Management REST API built with Go and Gin.
17+
18+
// @contact.name API Support
19+
// @contact.url https://github.com/kunalkumar-1/Evently
20+
// @contact.email [email protected]
21+
22+
// @license.name MIT
23+
// @license.url https://opensource.org/licenses/MIT
24+
25+
// @host localhost:8080
26+
// @BasePath /api/v1
27+
// @schemes http
28+
1329
type application struct {
1430
port int
1531
jwtSecret string

‎cmd/api/routes.go‎

Lines changed: 9 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -4,6 +4,8 @@ import (
44
"net/http"
55

66
"github.com/gin-gonic/gin"
7+
swaggerFiles "github.com/swaggo/files"
8+
ginSwagger "github.com/swaggo/gin-swagger"
79
)
810

911
func (app *application) routes() http.Handler {
@@ -29,5 +31,12 @@ func (app *application) routes() http.Handler {
2931
auth.DELETE("/events/:id/attendees/:userId", app.deleteAttendeeFromEvent) // delete attendee from event
3032
}
3133

34+
r.GET("/swagger/*any", func(c *gin.Context) {
35+
if c.Request.RequestURI == "/swagger/" {
36+
c.Redirect(302, "/swagger/index.html")
37+
}
38+
ginSwagger.WrapHandler(swaggerFiles.Handler, ginSwagger.URL("http://localhost:8080/swagger/doc.json"))(c)
39+
})
40+
3241
return r
3342
}

0 commit comments

Comments
 (0)