feat: 完善Swagger API文档生成功能

This commit is contained in:
wizardchen
2025-12-16 16:40:13 +08:00
committed by lyingbug
parent 121e9b3e1b
commit a7df6900eb
26 changed files with 20941 additions and 206 deletions
+57 -5
View File
@@ -39,7 +39,17 @@ func NewHandler(
}
}
// CreateSession handles the creation of a new conversation session
// CreateSession godoc
// @Summary 创建会话
// @Description 创建新的对话会话
// @Tags 会话
// @Accept json
// @Produce json
// @Param request body CreateSessionRequest true "会话创建请求"
// @Success 201 {object} map[string]interface{} "创建的会话"
// @Failure 400 {object} errors.AppError "请求参数错误"
// @Security Bearer
// @Router /sessions [post]
func (h *Handler) CreateSession(c *gin.Context) {
ctx := c.Request.Context()
// Parse and validate the request body
@@ -187,7 +197,17 @@ func (h *Handler) applyConversationDefaults(ctx context.Context, session *types.
session.SummaryParameters = h.createDefaultSummaryConfig(ctx)
}
// GetSession retrieves a session by its ID
// GetSession godoc
// @Summary 获取会话详情
// @Description 根据ID获取会话详情
// @Tags 会话
// @Accept json
// @Produce json
// @Param id path string true "会话ID"
// @Success 200 {object} map[string]interface{} "会话详情"
// @Failure 404 {object} errors.AppError "会话不存在"
// @Security Bearer
// @Router /sessions/{id} [get]
func (h *Handler) GetSession(c *gin.Context) {
ctx := c.Request.Context()
@@ -223,7 +243,18 @@ func (h *Handler) GetSession(c *gin.Context) {
})
}
// GetSessionsByTenant retrieves all sessions for the current tenant with pagination
// GetSessionsByTenant godoc
// @Summary 获取会话列表
// @Description 获取当前租户的会话列表,支持分页
// @Tags 会话
// @Accept json
// @Produce json
// @Param page query int false "页码"
// @Param page_size query int false "每页数量"
// @Success 200 {object} map[string]interface{} "会话列表"
// @Failure 400 {object} errors.AppError "请求参数错误"
// @Security Bearer
// @Router /sessions [get]
func (h *Handler) GetSessionsByTenant(c *gin.Context) {
ctx := c.Request.Context()
@@ -253,7 +284,18 @@ func (h *Handler) GetSessionsByTenant(c *gin.Context) {
})
}
// UpdateSession updates an existing session's properties
// UpdateSession godoc
// @Summary 更新会话
// @Description 更新会话属性
// @Tags 会话
// @Accept json
// @Produce json
// @Param id path string true "会话ID"
// @Param request body types.Session true "会话信息"
// @Success 200 {object} map[string]interface{} "更新后的会话"
// @Failure 404 {object} errors.AppError "会话不存在"
// @Security Bearer
// @Router /sessions/{id} [put]
func (h *Handler) UpdateSession(c *gin.Context) {
ctx := c.Request.Context()
@@ -304,7 +346,17 @@ func (h *Handler) UpdateSession(c *gin.Context) {
})
}
// DeleteSession deletes a session by its ID
// DeleteSession godoc
// @Summary 删除会话
// @Description 删除指定的会话
// @Tags 会话
// @Accept json
// @Produce json
// @Param id path string true "会话ID"
// @Success 200 {object} map[string]interface{} "删除成功"
// @Failure 404 {object} errors.AppError "会话不存在"
// @Security Bearer
// @Router /sessions/{id} [delete]
func (h *Handler) DeleteSession(c *gin.Context) {
ctx := c.Request.Context()
+35 -3
View File
@@ -16,7 +16,17 @@ import (
"github.com/gin-gonic/gin"
)
// SearchKnowledge performs knowledge base search without LLM summarization
// SearchKnowledge godoc
// @Summary 知识搜索
// @Description 在知识库中搜索(不使用LLM总结)
// @Tags 问答
// @Accept json
// @Produce json
// @Param request body SearchKnowledgeRequest true "搜索请求"
// @Success 200 {object} map[string]interface{} "搜索结果"
// @Failure 400 {object} errors.AppError "请求参数错误"
// @Security Bearer
// @Router /sessions/search [post]
func (h *Handler) SearchKnowledge(c *gin.Context) {
ctx := logger.CloneContext(c.Request.Context())
@@ -67,7 +77,18 @@ func (h *Handler) SearchKnowledge(c *gin.Context) {
})
}
// KnowledgeQA handles knowledge base question answering requests with LLM summarization
// KnowledgeQA godoc
// @Summary 知识问答
// @Description 基于知识库的问答(使用LLM总结),支持SSE流式响应
// @Tags 问答
// @Accept json
// @Produce text/event-stream
// @Param session_id path string true "会话ID"
// @Param request body CreateKnowledgeQARequest true "问答请求"
// @Success 200 {object} map[string]interface{} "问答结果(SSE流)"
// @Failure 400 {object} errors.AppError "请求参数错误"
// @Security Bearer
// @Router /sessions/{session_id}/knowledge-qa [post]
func (h *Handler) KnowledgeQA(c *gin.Context) {
ctx := logger.CloneContext(c.Request.Context())
@@ -136,7 +157,18 @@ func (h *Handler) KnowledgeQA(c *gin.Context) {
assistantMessage, true, secutils.SanitizeForLog(request.SummaryModelID), request.WebSearchEnabled)
}
// AgentQA handles agent-based question answering with conversation history and streaming
// AgentQA godoc
// @Summary Agent问答
// @Description 基于Agent的智能问答,支持多轮对话和SSE流式响应
// @Tags 问答
// @Accept json
// @Produce text/event-stream
// @Param session_id path string true "会话ID"
// @Param request body CreateKnowledgeQARequest true "问答请求"
// @Success 200 {object} map[string]interface{} "问答结果(SSE流)"
// @Failure 400 {object} errors.AppError "请求参数错误"
// @Security Bearer
// @Router /sessions/{session_id}/agent-qa [post]
func (h *Handler) AgentQA(c *gin.Context) {
ctx := logger.CloneContext(c.Request.Context())
logger.Info(ctx, "Start processing agent QA request")
+24 -2
View File
@@ -15,7 +15,18 @@ import (
"github.com/gin-gonic/gin"
)
// ContinueStream handles continued streaming of an active response stream
// ContinueStream godoc
// @Summary 继续流式响应
// @Description 继续获取正在进行的流式响应
// @Tags 问答
// @Accept json
// @Produce text/event-stream
// @Param session_id path string true "会话ID"
// @Param message_id query string true "消息ID"
// @Success 200 {object} map[string]interface{} "流式响应"
// @Failure 404 {object} errors.AppError "会话或消息不存在"
// @Security Bearer
// @Router /sessions/{session_id}/continue [get]
func (h *Handler) ContinueStream(c *gin.Context) {
ctx := c.Request.Context()
@@ -163,7 +174,18 @@ func (h *Handler) ContinueStream(c *gin.Context) {
}
}
// StopSession handles the stop generation request
// StopSession godoc
// @Summary 停止生成
// @Description 停止当前正在进行的生成任务
// @Tags 问答
// @Accept json
// @Produce json
// @Param session_id path string true "会话ID"
// @Param request body StopSessionRequest true "停止请求"
// @Success 200 {object} map[string]interface{} "停止成功"
// @Failure 404 {object} errors.AppError "会话或消息不存在"
// @Security Bearer
// @Router /sessions/{session_id}/stop [post]
func (h *Handler) StopSession(c *gin.Context) {
ctx := logger.CloneContext(c.Request.Context())
sessionID := secutils.SanitizeForLog(c.Param("session_id"))
+12 -1
View File
@@ -8,7 +8,18 @@ import (
"github.com/gin-gonic/gin"
)
// GenerateTitle generates a title for a session based on message content
// GenerateTitle godoc
// @Summary 生成会话标题
// @Description 根据消息内容自动生成会话标题
// @Tags 会话
// @Accept json
// @Produce json
// @Param session_id path string true "会话ID"
// @Param request body GenerateTitleRequest true "生成请求"
// @Success 200 {object} map[string]interface{} "生成的标题"
// @Failure 400 {object} errors.AppError "请求参数错误"
// @Security Bearer
// @Router /sessions/{session_id}/title [post]
func (h *Handler) GenerateTitle(c *gin.Context) {
ctx := c.Request.Context()