feat: Add Swagger documentation for admin and master API endpoints

- Added Swagger documentation for the following admin endpoints:
  - Create a new master tenant
  - Create a new provider
  - Register a new model
  - List all models
  - Update a model
  - Force sync snapshot
  - Ingest logs

- Added Swagger documentation for the master endpoint:
  - Issue a child key

- Updated go.mod and go.sum to include necessary dependencies for Swagger.

internal/api/admin_handler.go

@@ -23,6 +23,18 @@ type CreateMasterRequest struct {
 	GlobalQPS    int    `json:"global_qps"`
 }
 
+// CreateMaster godoc
+// @Summary      Create a new master tenant
+// @Description  Create a new master account (tenant)
+// @Tags         admin
+// @Accept       json
+// @Produce      json
+// @Security     AdminAuth
+// @Param        master  body      CreateMasterRequest  true  "Master Info"
+// @Success      201     {object}  gin.H
+// @Failure      400     {object}  gin.H
+// @Failure      500     {object}  gin.H
+// @Router       /admin/masters [post]
 func (h *AdminHandler) CreateMaster(c *gin.Context) {
 	var req CreateMasterRequest
 	if err := c.ShouldBindJSON(&req); err != nil {

internal/api/handler.go

@@ -24,6 +24,18 @@ func NewHandler(db *gorm.DB, sync *service.SyncService, logger *service.LogWrite
 
 // CreateKey is now handled by MasterHandler
 
+// CreateProvider godoc
+// @Summary      Create a new provider
+// @Description  Register a new upstream AI provider
+// @Tags         admin
+// @Accept       json
+// @Produce      json
+// @Security     AdminAuth
+// @Param        provider  body      dto.ProviderDTO  true  "Provider Info"
+// @Success      201       {object}  model.Provider
+// @Failure      400       {object}  gin.H
+// @Failure      500       {object}  gin.H
+// @Router       /admin/providers [post]
 func (h *Handler) CreateProvider(c *gin.Context) {
 	var req dto.ProviderDTO
 	if err := c.ShouldBindJSON(&req); err != nil {
@@ -58,6 +70,18 @@ func (h *Handler) CreateProvider(c *gin.Context) {
 	c.JSON(http.StatusCreated, provider)
 }
 
+// CreateModel godoc
+// @Summary      Register a new model
+// @Description  Register a supported model with its capabilities
+// @Tags         admin
+// @Accept       json
+// @Produce      json
+// @Security     AdminAuth
+// @Param        model  body      dto.ModelDTO  true  "Model Info"
+// @Success      201    {object}  model.Model
+// @Failure      400    {object}  gin.H
+// @Failure      500    {object}  gin.H
+// @Router       /admin/models [post]
 func (h *Handler) CreateModel(c *gin.Context) {
 	var req dto.ModelDTO
 	if err := c.ShouldBindJSON(&req); err != nil {
@@ -89,6 +113,15 @@ func (h *Handler) CreateModel(c *gin.Context) {
 	c.JSON(http.StatusCreated, modelReq)
 }
 
+// ListModels godoc
+// @Summary      List all models
+// @Description  Get a list of all registered models
+// @Tags         admin
+// @Produce      json
+// @Security     AdminAuth
+// @Success      200  {array}   model.Model
+// @Failure      500  {object}  gin.H
+// @Router       /admin/models [get]
 func (h *Handler) ListModels(c *gin.Context) {
 	var models []model.Model
 	if err := h.db.Find(&models).Error; err != nil {
@@ -98,6 +131,20 @@ func (h *Handler) ListModels(c *gin.Context) {
 	c.JSON(http.StatusOK, models)
 }
 
+// UpdateModel godoc
+// @Summary      Update a model
+// @Description  Update an existing model's configuration
+// @Tags         admin
+// @Accept       json
+// @Produce      json
+// @Security     AdminAuth
+// @Param        id     path      int           true  "Model ID"
+// @Param        model  body      dto.ModelDTO  true  "Model Info"
+// @Success      200    {object}  model.Model
+// @Failure      400    {object}  gin.H
+// @Failure      404    {object}  gin.H
+// @Failure      500    {object}  gin.H
+// @Router       /admin/models/{id} [put]
 func (h *Handler) UpdateModel(c *gin.Context) {
 	idParam := c.Param("id")
 	id, err := strconv.Atoi(idParam)
@@ -140,6 +187,15 @@ func (h *Handler) UpdateModel(c *gin.Context) {
 	c.JSON(http.StatusOK, existing)
 }
 
+// SyncSnapshot godoc
+// @Summary      Force sync snapshot
+// @Description  Force full synchronization of DB state to Redis
+// @Tags         admin
+// @Produce      json
+// @Security     AdminAuth
+// @Success      200  {object}  gin.H
+// @Failure      500  {object}  gin.H
+// @Router       /admin/sync/snapshot [post]
 func (h *Handler) SyncSnapshot(c *gin.Context) {
 	if err := h.sync.SyncAll(h.db); err != nil {
 		c.JSON(http.StatusInternalServerError, gin.H{"error": "Failed to sync snapshots", "details": err.Error()})
@@ -149,6 +205,15 @@ func (h *Handler) SyncSnapshot(c *gin.Context) {
 }
 
 // IngestLog accepts log records from data plane or other services.
+// @Summary      Ingest logs
+// @Description  Internal endpoint for ingesting logs from Balancer
+// @Tags         system
+// @Accept       json
+// @Produce      json
+// @Param        log  body      model.LogRecord  true  "Log Record"
+// @Success      202  {object}  gin.H
+// @Failure      400  {object}  gin.H
+// @Router       /logs [post]
 func (h *Handler) IngestLog(c *gin.Context) {
 	var rec model.LogRecord
 	if err := c.ShouldBindJSON(&rec); err != nil {

internal/api/master_handler.go

@@ -23,6 +23,20 @@ type IssueChildKeyRequest struct {
 	Scopes string `json:"scopes"`
 }
 
+// IssueChildKey godoc
+// @Summary      Issue a child key
+// @Description  Issue a new access token (child key) for the authenticated master
+// @Tags         master
+// @Accept       json
+// @Produce      json
+// @Security     MasterAuth
+// @Param        request  body      IssueChildKeyRequest  true  "Key Request"
+// @Success      201      {object}  gin.H
+// @Failure      400      {object}  gin.H
+// @Failure      401      {object}  gin.H
+// @Failure      403      {object}  gin.H
+// @Failure      500      {object}  gin.H
+// @Router       /v1/tokens [post]
 func (h *MasterHandler) IssueChildKey(c *gin.Context) {
 	master, exists := c.Get("master")
 	if !exists {