BCAI/easyai-ai-gateway
3
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

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

Browse Source 
为接口、模型与脚本补齐 Swagger/OpenAPI 注释，生成最新文档，并增加一键生成与查看入口。
This commit is contained in:
chensipeng
2026-05-14 18:18:27 +08:00
parent 2685450f3e
commit 918dfbfee1
18 changed files with 16240 additions and 7 deletions
Download Patch File Download Diff File Expand all files Collapse all files
apps/api/internal/httpapi/identity_admin_handlers.go
+135
View File
@@ -8,6 +8,21 @@ import (
"github.com/easyai/easyai-ai-gateway/apps/api/internal/store"
)
// createTenant godoc
// @Summary 创建租户
// @Description 管理端创建网关租户，tenantKey 和 name 必填。
// @Tags identity
// @Accept json
// @Produce json
// @Security BearerAuth
// @Param input body store.GatewayTenantInput true "租户请求"
// @Success 201 {object} store.GatewayTenant
// @Failure 400 {object} ErrorEnvelope
// @Failure 401 {object} ErrorEnvelope
// @Failure 403 {object} ErrorEnvelope
// @Failure 409 {object} ErrorEnvelope
// @Failure 500 {object} ErrorEnvelope
// @Router /api/admin/tenants [post]
func (s *Server) createTenant(w http.ResponseWriter, r *http.Request) {
var input store.GatewayTenantInput
if err := json.NewDecoder(r.Body).Decode(&input); err != nil {
@@ -31,6 +46,23 @@ func (s *Server) createTenant(w http.ResponseWriter, r *http.Request) {
writeJSON(w, http.StatusCreated, item)
}
// updateTenant godoc
// @Summary 更新租户
// @Description 管理端更新网关租户信息。
// @Tags identity
// @Accept json
// @Produce json
// @Security BearerAuth
// @Param tenantID path string true "租户 ID"
// @Param input body store.GatewayTenantInput true "租户请求"
// @Success 200 {object} store.GatewayTenant
// @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/tenants/{tenantID} [patch]
func (s *Server) updateTenant(w http.ResponseWriter, r *http.Request) {
var input store.GatewayTenantInput
if err := json.NewDecoder(r.Body).Decode(&input); err != nil {
@@ -58,6 +90,19 @@ func (s *Server) updateTenant(w http.ResponseWriter, r *http.Request) {
writeJSON(w, http.StatusOK, item)
}
// deleteTenant godoc
// @Summary 删除租户
// @Description 管理端删除网关租户。
// @Tags identity
// @Produce json
// @Security BearerAuth
// @Param tenantID 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/tenants/{tenantID} [delete]
func (s *Server) deleteTenant(w http.ResponseWriter, r *http.Request) {
if err := s.store.DeleteTenant(r.Context(), r.PathValue("tenantID")); err != nil {
if store.IsNotFound(err) {
@@ -71,6 +116,21 @@ func (s *Server) deleteTenant(w http.ResponseWriter, r *http.Request) {
w.WriteHeader(http.StatusNoContent)
}
// createGatewayUser godoc
// @Summary 创建用户
// @Description 管理端创建网关用户；password 为空时不设置本地密码，非空时至少 8 位。
// @Tags identity
// @Accept json
// @Produce json
// @Security BearerAuth
// @Param input body store.GatewayUserInput true "用户请求"
// @Success 201 {object} store.GatewayUser
// @Failure 400 {object} ErrorEnvelope
// @Failure 401 {object} ErrorEnvelope
// @Failure 403 {object} ErrorEnvelope
// @Failure 409 {object} ErrorEnvelope
// @Failure 500 {object} ErrorEnvelope
// @Router /api/admin/users [post]
func (s *Server) createGatewayUser(w http.ResponseWriter, r *http.Request) {
var input store.GatewayUserInput
if err := json.NewDecoder(r.Body).Decode(&input); err != nil {
@@ -98,6 +158,23 @@ func (s *Server) createGatewayUser(w http.ResponseWriter, r *http.Request) {
writeJSON(w, http.StatusCreated, item)
}
// updateGatewayUser godoc
// @Summary 更新用户
// @Description 管理端更新网关用户资料、角色、默认用户组和可选本地密码。
// @Tags identity
// @Accept json
// @Produce json
// @Security BearerAuth
// @Param userID path string true "用户 ID"
// @Param input body store.GatewayUserInput true "用户请求"
// @Success 200 {object} store.GatewayUser
// @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/users/{userID} [patch]
func (s *Server) updateGatewayUser(w http.ResponseWriter, r *http.Request) {
var input store.GatewayUserInput
if err := json.NewDecoder(r.Body).Decode(&input); err != nil {
@@ -129,6 +206,19 @@ func (s *Server) updateGatewayUser(w http.ResponseWriter, r *http.Request) {
writeJSON(w, http.StatusOK, item)
}
// deleteGatewayUser godoc
// @Summary 删除用户
// @Description 管理端删除网关用户。
// @Tags identity
// @Produce json
// @Security BearerAuth
// @Param userID 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/users/{userID} [delete]
func (s *Server) deleteGatewayUser(w http.ResponseWriter, r *http.Request) {
if err := s.store.DeleteGatewayUser(r.Context(), r.PathValue("userID")); err != nil {
if store.IsNotFound(err) {
@@ -142,6 +232,21 @@ func (s *Server) deleteGatewayUser(w http.ResponseWriter, r *http.Request) {
w.WriteHeader(http.StatusNoContent)
}
// createUserGroup godoc
// @Summary 创建用户组
// @Description 管理端创建用户组，可配置默认定价、运行策略、限流和配额策略。
// @Tags identity
// @Accept json
// @Produce json
// @Security BearerAuth
// @Param input body store.UserGroupInput true "用户组请求"
// @Success 201 {object} store.UserGroup
// @Failure 400 {object} ErrorEnvelope
// @Failure 401 {object} ErrorEnvelope
// @Failure 403 {object} ErrorEnvelope
// @Failure 409 {object} ErrorEnvelope
// @Failure 500 {object} ErrorEnvelope
// @Router /api/admin/user-groups [post]
func (s *Server) createUserGroup(w http.ResponseWriter, r *http.Request) {
var input store.UserGroupInput
if err := json.NewDecoder(r.Body).Decode(&input); err != nil {
@@ -165,6 +270,23 @@ func (s *Server) createUserGroup(w http.ResponseWriter, r *http.Request) {
writeJSON(w, http.StatusCreated, item)
}
// updateUserGroup godoc
// @Summary 更新用户组
// @Description 管理端更新用户组基础信息和策略配置。
// @Tags identity
// @Accept json
// @Produce json
// @Security BearerAuth
// @Param groupID path string true "用户组 ID"
// @Param input body store.UserGroupInput true "用户组请求"
// @Success 200 {object} store.UserGroup
// @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/user-groups/{groupID} [patch]
func (s *Server) updateUserGroup(w http.ResponseWriter, r *http.Request) {
var input store.UserGroupInput
if err := json.NewDecoder(r.Body).Decode(&input); err != nil {
@@ -192,6 +314,19 @@ func (s *Server) updateUserGroup(w http.ResponseWriter, r *http.Request) {
writeJSON(w, http.StatusOK, item)
}
// deleteUserGroup godoc
// @Summary 删除用户组
// @Description 管理端删除用户组。
// @Tags identity
// @Produce json
// @Security BearerAuth
// @Param groupID 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/user-groups/{groupID} [delete]
func (s *Server) deleteUserGroup(w http.ResponseWriter, r *http.Request) {
if err := s.store.DeleteUserGroup(r.Context(), r.PathValue("groupID")); err != nil {
if store.IsNotFound(err) {