pig/pig-farm-controller
1
0
Fork 0
Code Issues 11 Pull Requests Actions Packages Projects Releases Wiki Activity

实现swagger

Browse Source
This commit is contained in:
huang
2025-09-12 17:43:42 +08:00
parent fe9b0db985
commit 9e9bf7b8a0
6 changed files with 745 additions and 197 deletions
Download Patch File Download Diff File Expand all files Collapse all files

104
internal/app/controller/device/device_controller.go
View File

@@ -5,6 +5,7 @@ import (
"net/http"
"strconv"
"strings"
"time"
"git.huangwc.com/pig/pig-farm-controller/internal/app/controller"
"git.huangwc.com/pig/pig-farm-controller/internal/infra/logs"
@@ -29,39 +30,83 @@ func NewController(repo repository.DeviceRepository, logger *logs.Logger) *Contr
}
}
// --- Request & Response Structs ---
// --- Request DTOs ---
// CreateDeviceRequest 定义了创建设备时需要传入的参数
type CreateDeviceRequest struct {
Name string `json:"name" binding:"required"`
Type models.DeviceType `json:"type" binding:"required"`
SubType models.DeviceSubType `json:"sub_type,omitempty"`
ParentID *uint `json:"parent_id,omitempty"`
Location string `json:"location,omitempty"`
Properties datatypes.JSON `json:"properties,omitempty"`
Name string `json:"name" binding:"required"`
Type models.DeviceType `json:"type" binding:"required"`
SubType models.DeviceSubType `json:"sub_type,omitempty"`
ParentID *uint `json:"parent_id,omitempty"`
Location string `json:"location,omitempty"`
Properties controller.Properties `json:"properties,omitempty"`
}
// UpdateDeviceRequest 定义了更新设备时需要传入的参数
type UpdateDeviceRequest struct {
Name string `json:"name" binding:"required"`
Type models.DeviceType `json:"type" binding:"required"`
SubType models.DeviceSubType `json:"sub_type,omitempty"`
ParentID *uint `json:"parent_id,omitempty"`
Location string `json:"location,omitempty"`
Properties datatypes.JSON `json:"properties,omitempty"`
Name string `json:"name" binding:"required"`
Type models.DeviceType `json:"type" binding:"required"`
SubType models.DeviceSubType `json:"sub_type,omitempty"`
ParentID *uint `json:"parent_id,omitempty"`
Location string `json:"location,omitempty"`
Properties controller.Properties `json:"properties,omitempty"`
}
// --- Response DTOs ---
// DeviceResponse 定义了返回给客户端的单个设备信息的结构
type DeviceResponse struct {
ID uint `json:"id"`
Name string `json:"name"`
Type models.DeviceType `json:"type"`
SubType models.DeviceSubType `json:"sub_type"`
ParentID *uint `json:"parent_id"`
Location string `json:"location"`
Properties controller.Properties `json:"properties"`
CreatedAt string `json:"created_at"`
UpdatedAt string `json:"updated_at"`
}
// --- DTO 转换函数 ---
// newDeviceResponse 从数据库模型创建一个新的设备响应 DTO
func newDeviceResponse(device *models.Device) *DeviceResponse {
if device == nil {
return nil
}
return &DeviceResponse{
ID: device.ID,
Name: device.Name,
Type: device.Type,
SubType: device.SubType,
ParentID: device.ParentID,
Location: device.Location,
Properties: controller.Properties(device.Properties),
CreatedAt: device.CreatedAt.Format(time.RFC3339),
UpdatedAt: device.UpdatedAt.Format(time.RFC3339),
}
}
// newListDeviceResponse 从数据库模型切片创建一个新的设备列表响应 DTO 切片
func newListDeviceResponse(devices []*models.Device) []*DeviceResponse {
list := make([]*DeviceResponse, 0, len(devices))
for _, device := range devices {
list = append(list, newDeviceResponse(device))
}
return list
}
// --- Controller Methods ---
// CreateDevice godoc
// @Summary 创建新设备
// @Description 根据提供的信息创建一个新设备，可以是区域主控或普通设备
// @Description 根据提供的信息创建一个新设备
// @Tags 设备管理
// @Accept json
// @Produce json
// @Param device body CreateDeviceRequest true "设备信息"
// @Success 200 {object} controller.Response{data=models.Device} "业务码为201代表创建成功"
// @Failure 200 {object} controller.Response "业务失败，具体错误码和信息见响应体（例如400, 500）"
// @Success 200 {object} controller.Response{data=DeviceResponse} "业务码为201代表创建成功"
// @Failure 200 {object} controller.Response "业务失败，具体错误码和信息见响应体"
// @Router /devices [post]
func (c *Controller) CreateDevice(ctx *gin.Context) {
var req CreateDeviceRequest
@@ -77,7 +122,7 @@ func (c *Controller) CreateDevice(ctx *gin.Context) {
SubType: req.SubType,
ParentID: req.ParentID,
Location: req.Location,
Properties: req.Properties,
Properties: datatypes.JSON(req.Properties),
}
if err := c.repo.Create(device); err != nil {
@@ -86,7 +131,7 @@ func (c *Controller) CreateDevice(ctx *gin.Context) {
return
}
controller.SendResponse(ctx, http.StatusCreated, "设备创建成功", device)
controller.SendResponse(ctx, http.StatusCreated, "设备创建成功", newDeviceResponse(device))
}
// GetDevice godoc
@@ -95,8 +140,8 @@ func (c *Controller) CreateDevice(ctx *gin.Context) {
// @Tags 设备管理
// @Produce json
// @Param id path string true "设备ID"
// @Success 200 {object} controller.Response{data=models.Device} "业务码为200代表获取成功"
// @Failure 200 {object} controller.Response "业务失败，具体错误码和信息见响应体（例如400, 404, 500）"
// @Success 200 {object} controller.Response{data=DeviceResponse} "业务码为200代表获取成功"
// @Failure 200 {object} controller.Response "业务失败，具体错误码和信息见响应体"
// @Router /devices/{id} [get]
func (c *Controller) GetDevice(ctx *gin.Context) {
deviceID := ctx.Param("id")
@@ -107,7 +152,6 @@ func (c *Controller) GetDevice(ctx *gin.Context) {
controller.SendErrorResponse(ctx, http.StatusNotFound, "设备未找到")
return
}
// 检查是否是ID格式错误
if strings.Contains(err.Error(), "无效的设备ID格式") {
controller.SendErrorResponse(ctx, http.StatusBadRequest, err.Error())
return
@@ -117,7 +161,7 @@ func (c *Controller) GetDevice(ctx *gin.Context) {
return
}
controller.SendResponse(ctx, http.StatusOK, "获取设备信息成功", device)
controller.SendResponse(ctx, http.StatusOK, "获取设备信息成功", newDeviceResponse(device))
}
// ListDevices godoc
@@ -125,8 +169,8 @@ func (c *Controller) GetDevice(ctx *gin.Context) {
// @Description 获取系统中所有设备的列表
// @Tags 设备管理
// @Produce json
// @Success 200 {object} controller.Response{data=[]models.Device} "业务码为200代表获取成功"
// @Failure 200 {object} controller.Response "业务失败，具体错误码和信息见响应体（例如500）"
// @Success 200 {object} controller.Response{data=[]DeviceResponse} "业务码为200代表获取成功"
// @Failure 200 {object} controller.Response "业务失败，具体错误码和信息见响应体"
// @Router /devices [get]
func (c *Controller) ListDevices(ctx *gin.Context) {
devices, err := c.repo.ListAll()
@@ -136,7 +180,7 @@ func (c *Controller) ListDevices(ctx *gin.Context) {
return
}
controller.SendResponse(ctx, http.StatusOK, "获取设备列表成功", devices)
controller.SendResponse(ctx, http.StatusOK, "获取设备列表成功", newListDeviceResponse(devices))
}
// UpdateDevice godoc
@@ -147,8 +191,8 @@ func (c *Controller) ListDevices(ctx *gin.Context) {
// @Produce json
// @Param id path string true "设备ID"
// @Param device body UpdateDeviceRequest true "要更新的设备信息"
// @Success 200 {object} controller.Response{data=models.Device} "业务码为200代表更新成功"
// @Failure 200 {object} controller.Response "业务失败，具体错误码和信息见响应体（例如400, 404, 500）"
// @Success 200 {object} controller.Response{data=DeviceResponse} "业务码为200代表更新成功"
// @Failure 200 {object} controller.Response "业务失败，具体错误码和信息见响应体"
// @Router /devices/{id} [put]
func (c *Controller) UpdateDevice(ctx *gin.Context) {
deviceID := ctx.Param("id")
@@ -183,7 +227,7 @@ func (c *Controller) UpdateDevice(ctx *gin.Context) {
existingDevice.SubType = req.SubType
existingDevice.ParentID = req.ParentID
existingDevice.Location = req.Location
existingDevice.Properties = req.Properties
existingDevice.Properties = datatypes.JSON(req.Properties)
// 4. 保存到数据库
if err := c.repo.Update(existingDevice); err != nil {
@@ -192,7 +236,7 @@ func (c *Controller) UpdateDevice(ctx *gin.Context) {
return
}
controller.SendResponse(ctx, http.StatusOK, "设备更新成功", existingDevice)
controller.SendResponse(ctx, http.StatusOK, "设备更新成功", newDeviceResponse(existingDevice))
}
// DeleteDevice godoc
@@ -202,7 +246,7 @@ func (c *Controller) UpdateDevice(ctx *gin.Context) {
// @Produce json
// @Param id path string true "设备ID"
// @Success 200 {object} controller.Response "业务码为200代表删除成功"
// @Failure 200 {object} controller.Response "业务失败，具体错误码和信息见响应体（例如400, 500）"
// @Failure 200 {object} controller.Response "业务失败，具体错误码和信息见响应体"
// @Router /devices/{id} [delete]
func (c *Controller) DeleteDevice(ctx *gin.Context) {
deviceID := ctx.Param("id")

8
internal/app/controller/response.go
View File

@@ -1,11 +1,14 @@
package controller
import (
"encoding/json"
"net/http"
"github.com/gin-gonic/gin"
)
// --- 通用响应结构 ---
// Response 定义统一的API响应结构体
type Response struct {
Code int `json:"code"` // 业务状态码
@@ -14,7 +17,6 @@ type Response struct {
}
// SendResponse 发送统一格式的JSON响应
// httpStatus 参数现在将几乎总是 http.StatusOK，业务状态码通过 Response.Code 传递
func SendResponse(ctx *gin.Context, code int, message string, data interface{}) {
ctx.JSON(http.StatusOK, Response{
Code: code,
@@ -24,7 +26,9 @@ func SendResponse(ctx *gin.Context, code int, message string, data interface{})
}
// SendErrorResponse 发送统一格式的错误响应
// 错误响应通常不包含业务数据，因此 data 参数固定为 nil
func SendErrorResponse(ctx *gin.Context, code int, message string) {
SendResponse(ctx, code, message, nil)
}
// Properties 是一个自定义类型，用于在 Swagger 中正确表示 JSON 对象
type Properties json.RawMessage

4
internal/app/controller/user/user_controller.go
View File

@@ -60,7 +60,7 @@ type LoginResponse struct {
// @Accept json
// @Produce json
// @Param user body CreateUserRequest true "用户信息"
// @Success 200 {object} controller.Response{data=CreateUserResponse} "业务码为201代表创建成功"
// @Success 200 {object} controller.Response{data=user.CreateUserResponse} "业务码为201代表创建成功"
// @Failure 200 {object} controller.Response "业务失败，具体错误码和信息见响应体（例如400, 409, 500）"
// @Router /users [post]
func (c *Controller) CreateUser(ctx *gin.Context) {
@@ -104,7 +104,7 @@ func (c *Controller) CreateUser(ctx *gin.Context) {
// @Accept json
// @Produce json
// @Param credentials body LoginRequest true "登录凭证"
// @Success 200 {object} controller.Response{data=LoginResponse} "业务码为200代表登录成功"
// @Success 200 {object} controller.Response{data=user.LoginResponse} "业务码为200代表登录成功"
// @Failure 200 {object} controller.Response "业务失败，具体错误码和信息见响应体（例如400, 401, 500）"
// @Router /users/login [post]
func (c *Controller) Login(ctx *gin.Context) {