feat: add docs

internal/handler/contact_handler.go

@@ -28,6 +28,15 @@ func HandleContacts(mux *http.ServeMux, repo repository.Repository[models.Contac
 	NewBaseHandler(mux, routes)
 }
 
+// GetAll godoc
+// @Summary Get all contacts
+// @Description Get a list of all contacts
+// @Tags contacts
+// @Accept json
+// @Produce json
+// @Success 200 {object} APIResponse{data=[]models.Contact}
+// @Failure 500 {object} APIResponse
+// @Router /contacts [get]
 func (h *ContactHandler) getAll(w http.ResponseWriter, r *http.Request) {
 	contacts, err := h.repository.GetAll()
 	if err != nil {
@@ -37,6 +46,18 @@ func (h *ContactHandler) getAll(w http.ResponseWriter, r *http.Request) {
 	JSONSuccess(w, contacts, "Contact list retrieved successfully", http.StatusOK)
 }
 
+// GetByID godoc
+// @Summary Get a contact by ID
+// @Description Get a single contact by its ID
+// @Tags contacts
+// @Accept json
+// @Produce json
+// @Param id path int true "Contact ID"
+// @Success 200 {object} APIResponse{data=models.Contact}
+// @Failure 400 {object} APIResponse
+// @Failure 404 {object} APIResponse
+// @Failure 500 {object} APIResponse
+// @Router /contacts/{id} [get]
 func (h *ContactHandler) getByID(w http.ResponseWriter, r *http.Request) {
 	id, err := strconv.Atoi(r.PathValue("id"))
 	if err != nil {
@@ -56,6 +77,17 @@ func (h *ContactHandler) getByID(w http.ResponseWriter, r *http.Request) {
 	JSONSuccess(w, contact, "Contact retrieved successfully", http.StatusOK)
 }
 
+// Create godoc
+// @Summary Create a new contact
+// @Description Create a new contact with the provided data
+// @Tags contacts
+// @Accept json
+// @Produce json
+// @Param contact body models.Contact true "Contact object"
+// @Success 201 {object} APIResponse{data=models.Contact}
+// @Failure 400 {object} APIResponse
+// @Failure 500 {object} APIResponse
+// @Router /contacts [post]
 func (h *ContactHandler) create(w http.ResponseWriter, r *http.Request) {
 
 	var contact models.Contact
@@ -89,6 +121,19 @@ func (h *ContactHandler) create(w http.ResponseWriter, r *http.Request) {
 	JSONSuccess(w, contact, "Contact created successfully", http.StatusCreated)
 }
 
+// Update godoc
+// @Summary Update a contact
+// @Description Update an existing contact by ID
+// @Tags contacts
+// @Accept json
+// @Produce json
+// @Param id path int true "Contact ID"
+// @Param contact body models.Contact true "Contact object"
+// @Success 200 {object} APIResponse
+// @Failure 400 {object} APIResponse
+// @Failure 404 {object} APIResponse
+// @Failure 500 {object} APIResponse
+// @Router /contacts/{id} [put]
 func (h *ContactHandler) update(w http.ResponseWriter, r *http.Request) {
 	id, err := strconv.Atoi(r.PathValue("id"))
 	if err != nil {
@@ -114,6 +159,18 @@ func (h *ContactHandler) update(w http.ResponseWriter, r *http.Request) {
 	JSONSuccess(w, nil, "Contact updated successfully", http.StatusOK)
 }
 
+// Delete godoc
+// @Summary Delete a contact
+// @Description Delete a contact by ID
+// @Tags contacts
+// @Accept json
+// @Produce json
+// @Param id path int true "Contact ID"
+// @Success 200 {object} APIResponse
+// @Failure 400 {object} APIResponse
+// @Failure 404 {object} APIResponse
+// @Failure 500 {object} APIResponse
+// @Router /contacts/{id} [delete]
 func (h *ContactHandler) delete(w http.ResponseWriter, r *http.Request) {
 	id, err := strconv.Atoi(r.PathValue("id"))
 

internal/handler/response.go

@@ -6,15 +6,22 @@ import (
 )
 
 type APIResponse struct {
-	Success bool       `json:"success"`
-	Data    any        `json:"data,omitempty"`
-	Errors  []APIError `json:"errors,omitempty"`
-	Message string     `json:"message,omitempty"`
+	// Indicates if the request was successful
+	Success bool `json:"success"`
+	// The response data
+	Data any `json:"data,omitempty"`
+	// List of errors if any occurred
+	Errors []APIError `json:"errors,omitempty"`
+	// Optional message
+	Message string `json:"message,omitempty"`
 }
 
 type APIError struct {
-	Code    int    `json:"code"`
+	// Error code
+	Code int `json:"code"`
+	// Human-readable error message
 	Message string `json:"message"`
+	// Additional error details
 	Details string `json:"details,omitempty"`
 }
 

internal/models/contact.go

@@ -1,8 +1,13 @@
 package models
 
+// Contact represents a contact entity
 type Contact struct {
-	ID      int    `json:"id" db:"id"`
-	Name    string `json:"name" db:"name"`
+	// ID is the unique identifier for the contact
+	ID int `json:"id" db:"id"`
+	// Name of the contact
+	Name string `json:"name" db:"name"`
+	// Company the contact works for
 	Company string `json:"company" db:"company"`
-	Phone   string `json:"phone" db:"phone"`
+	// Phone number in international format
+	Phone string `json:"phone" db:"phone"`
 }