docs(api): 补全 OpenAPI 注释与生成文档

为接口、模型与脚本补齐 Swagger/OpenAPI 注释，生成最新文档，并增加一键生成与查看入口。

apps/api/internal/httpapi/access_rule_handlers.go

@@ -10,6 +10,17 @@ import (
 	"github.com/easyai/easyai-ai-gateway/apps/api/internal/store"
 )
 
+// listAccessRules godoc
+// @Summary 列出访问规则
+// @Description 管理端返回用户组、租户、用户或 API Key 到平台、平台模型、基础模型的访问规则。
+// @Tags access-rules
+// @Produce json
+// @Security BearerAuth
+// @Success 200 {object} AccessRuleListResponse
+// @Failure 401 {object} ErrorEnvelope
+// @Failure 403 {object} ErrorEnvelope
+// @Failure 500 {object} ErrorEnvelope
+// @Router /api/admin/access-rules [get]
 func (s *Server) listAccessRules(w http.ResponseWriter, r *http.Request) {
 	items, err := s.store.ListAccessRules(r.Context())
 	if err != nil {
@@ -20,6 +31,17 @@ func (s *Server) listAccessRules(w http.ResponseWriter, r *http.Request) {
 	writeJSON(w, http.StatusOK, map[string]any{"items": items})
 }
 
+// listAPIKeyAccessRules godoc
+// @Summary 列出 API Key 访问规则
+// @Description 返回当前本地用户可管理的 API Key 访问规则。
+// @Tags api-keys
+// @Produce json
+// @Security BearerAuth
+// @Success 200 {object} AccessRuleListResponse
+// @Failure 400 {object} ErrorEnvelope
+// @Failure 401 {object} ErrorEnvelope
+// @Failure 500 {object} ErrorEnvelope
+// @Router /api/v1/api-keys/access-rules [get]
 func (s *Server) listAPIKeyAccessRules(w http.ResponseWriter, r *http.Request) {
 	user, _ := auth.UserFromContext(r.Context())
 	items, err := s.store.ListAPIKeyAccessRules(r.Context(), user)
@@ -35,6 +57,21 @@ func (s *Server) listAPIKeyAccessRules(w http.ResponseWriter, r *http.Request) {
 	writeJSON(w, http.StatusOK, map[string]any{"items": items})
 }
 
+// createAccessRule godoc
+// @Summary 创建访问规则
+// @Description 管理端创建一条访问控制规则。
+// @Tags access-rules
+// @Accept json
+// @Produce json
+// @Security BearerAuth
+// @Param input body store.AccessRuleInput true "访问规则请求"
+// @Success 201 {object} store.AccessRule
+// @Failure 400 {object} ErrorEnvelope
+// @Failure 401 {object} ErrorEnvelope
+// @Failure 403 {object} ErrorEnvelope
+// @Failure 409 {object} ErrorEnvelope
+// @Failure 500 {object} ErrorEnvelope
+// @Router /api/admin/access-rules [post]
 func (s *Server) createAccessRule(w http.ResponseWriter, r *http.Request) {
 	var input store.AccessRuleInput
 	if err := json.NewDecoder(r.Body).Decode(&input); err != nil {
@@ -58,6 +95,20 @@ func (s *Server) createAccessRule(w http.ResponseWriter, r *http.Request) {
 	writeJSON(w, http.StatusCreated, item)
 }
 
+// batchAccessRules godoc
+// @Summary 批量写入访问规则
+// @Description 管理端为同一主体批量新增、更新或删除资源访问规则。
+// @Tags access-rules
+// @Accept json
+// @Produce json
+// @Security BearerAuth
+// @Param input body store.AccessRuleBatchInput true "访问规则批量请求"
+// @Success 200 {object} AccessRuleListResponse
+// @Failure 400 {object} ErrorEnvelope
+// @Failure 401 {object} ErrorEnvelope
+// @Failure 403 {object} ErrorEnvelope
+// @Failure 500 {object} ErrorEnvelope
+// @Router /api/admin/access-rules/batch [post]
 func (s *Server) batchAccessRules(w http.ResponseWriter, r *http.Request) {
 	var input store.AccessRuleBatchInput
 	if err := json.NewDecoder(r.Body).Decode(&input); err != nil {
@@ -77,6 +128,21 @@ func (s *Server) batchAccessRules(w http.ResponseWriter, r *http.Request) {
 	writeJSON(w, http.StatusOK, map[string]any{"items": items})
 }
 
+// batchAPIKeyAccessRules godoc
+// @Summary 批量写入 API Key 访问规则
+// @Description 当前本地用户为自己的 API Key 批量新增、更新或删除可访问资源。
+// @Tags api-keys
+// @Accept json
+// @Produce json
+// @Security BearerAuth
+// @Param input body store.AccessRuleBatchInput true "API Key 访问规则批量请求，subjectType 必须为 api_key"
+// @Success 200 {object} AccessRuleListResponse
+// @Failure 400 {object} ErrorEnvelope
+// @Failure 401 {object} ErrorEnvelope
+// @Failure 403 {object} ErrorEnvelope
+// @Failure 404 {object} ErrorEnvelope
+// @Failure 500 {object} ErrorEnvelope
+// @Router /api/v1/api-keys/access-rules/batch [post]
 func (s *Server) batchAPIKeyAccessRules(w http.ResponseWriter, r *http.Request) {
 	user, _ := auth.UserFromContext(r.Context())
 	var input store.AccessRuleBatchInput
@@ -109,6 +175,23 @@ func (s *Server) batchAPIKeyAccessRules(w http.ResponseWriter, r *http.Request)
 	writeJSON(w, http.StatusOK, map[string]any{"items": items})
 }
 
+// updateAccessRule godoc
+// @Summary 更新访问规则
+// @Description 管理端更新一条访问控制规则。
+// @Tags access-rules
+// @Accept json
+// @Produce json
+// @Security BearerAuth
+// @Param ruleID path string true "访问规则 ID"
+// @Param input body store.AccessRuleInput true "访问规则请求"
+// @Success 200 {object} store.AccessRule
+// @Failure 400 {object} ErrorEnvelope
+// @Failure 401 {object} ErrorEnvelope
+// @Failure 403 {object} ErrorEnvelope
+// @Failure 404 {object} ErrorEnvelope
+// @Failure 409 {object} ErrorEnvelope
+// @Failure 500 {object} ErrorEnvelope
+// @Router /api/admin/access-rules/{ruleID} [patch]
 func (s *Server) updateAccessRule(w http.ResponseWriter, r *http.Request) {
 	var input store.AccessRuleInput
 	if err := json.NewDecoder(r.Body).Decode(&input); err != nil {
@@ -136,6 +219,19 @@ func (s *Server) updateAccessRule(w http.ResponseWriter, r *http.Request) {
 	writeJSON(w, http.StatusOK, item)
 }
 
+// deleteAccessRule godoc
+// @Summary 删除访问规则
+// @Description 管理端删除一条访问控制规则。
+// @Tags access-rules
+// @Produce json
+// @Security BearerAuth
+// @Param ruleID path string true "访问规则 ID"
+// @Success 204 "No Content"
+// @Failure 401 {object} ErrorEnvelope
+// @Failure 403 {object} ErrorEnvelope
+// @Failure 404 {object} ErrorEnvelope
+// @Failure 500 {object} ErrorEnvelope
+// @Router /api/admin/access-rules/{ruleID} [delete]
 func (s *Server) deleteAccessRule(w http.ResponseWriter, r *http.Request) {
 	if err := s.store.DeleteAccessRule(r.Context(), r.PathValue("ruleID")); err != nil {
 		if store.IsNotFound(err) {