Step 2: Swagger로 API 문서화하기

이제 RESTful API를 Swagger로 문서화해볼게요! 핸들러 함수에 Swagger 주석을 추가하고 문서를 생성해봅시다~ 🔄

internal/handler/todo.go 파일에 Swagger 주석 추가하기:

package handler

import (
    "net/http"
    "github.com/gin-gonic/gin"
    "github.com/yourusername/todo-api/pkg/api"
)

// TodoHandler handles HTTP requests for todo operations.
type TodoHandler struct {
    service api.TodoService
}

// NewTodoHandler creates a new TodoHandler with the given service.
func NewTodoHandler(service api.TodoService) *TodoHandler {
    return &TodoHandler{service: service}
}

// GetTodo godoc
// @Summary Get a todo item
// @Description Get a todo item by its ID
// @Tags todos
// @Accept json
// @Produce json
// @Param id path string true "Todo ID"
// @Success 200 {object} api.Todo
// @Failure 404 {object} ErrorResponse
// @Failure 500 {object} ErrorResponse
// @Router /todos/{id} [get]
func (h *TodoHandler) GetTodo(c *gin.Context) {
    id := c.Param("id")
    todo, err := h.service.GetTodo(id)
    if err != nil {
        c.JSON(http.StatusNotFound, ErrorResponse{Error: "Todo not found"})
        return
    }
    c.JSON(http.StatusOK, todo)
}

// ListTodos godoc
// @Summary List all todos
// @Description Get all todo items
// @Tags todos
// @Accept json
// @Produce json
// @Success 200 {array} api.Todo
// @Failure 500 {object} ErrorResponse
// @Router /todos [get]
func (h *TodoHandler) ListTodos(c *gin.Context) {
    todos, err := h.service.ListTodos()
    if err != nil {
        c.JSON(http.StatusInternalServerError, ErrorResponse{Error: "Failed to get todos"})
        return
    }
    c.JSON(http.StatusOK, todos)
}

// ErrorResponse represents an error response.
type ErrorResponse struct {
    Error string `json:"error"`
}

이제 Swagger 문서를 생성하고 서버에 통합해볼게요:

// main.go에 Swagger 초기화 코드 추가
package main

import (
    "github.com/gin-gonic/gin"
    "github.com/yourusername/todo-api/internal/handler"
    "github.com/yourusername/todo-api/internal/storage"
    
    swaggerFiles "github.com/swaggo/files"
    ginSwagger "github.com/swaggo/gin-swagger"
    
    // 생성된 docs 패키지 임포트
    _ "github.com/yourusername/todo-api/docs"
)

// @title Todo API
// @version 1.0
// @description A simple todo management API
// @host localhost:8080
// @BasePath /api/v1
func main() {
    // 스토리지 및 핸들러 초기화
    store := storage.NewMemoryStorage()
    todoHandler := handler.NewTodoHandler(store)
    
    // Gin 라우터 설정
    r := gin.Default()
    v1 := r.Group("/api/v1")
    {
        todos := v1.Group("/todos")
        {
            todos.GET("", todoHandler.ListTodos)
            todos.GET("/:id", todoHandler.GetTodo)
            todos.POST("", todoHandler.CreateTodo)
            todos.PUT("/:id", todoHandler.UpdateTodo)
            todos.DELETE("/:id", todoHandler.DeleteTodo)
        }
    }
    
    // Swagger UI 엔드포인트 추가
    r.GET("/swagger/*any", ginSwagger.WrapHandler(swaggerFiles.Handler))
    
    r.Run(":8080")
}

이제 swag init 명령어로 Swagger 문서를 생성하고, 서버를 실행한 후 http://localhost:8080/swagger/index.html에 접속하면 멋진 API 문서를 볼 수 있어요! 🎉