models swagger docs

models/document.go

@@ -6,13 +6,16 @@ import (
 	"github.com/google/uuid"
 )
 
-// Document — логическая сущность (например, пользователь, настройки и т.п.)
+// Document документ в системе
+// @Description Document — контейнер, объединяющий версии и снапшоты.
+// @Description Сам по себе не содержит данных (они находятся в версиях и снапшотах).
+// swagger:model Document
 type Document struct {
-	ID            uuid.UUID `gorm:"type:char(36);primaryKey"`
-	Name          string
-	CreatedAt     time.Time
-	UpdatedAt     time.Time
-	LatestVersion uuid.UUID `gorm:"type:char(36);"`
+	ID            uuid.UUID `json:"id" gorm:"type:char(36);primaryKey" example:"550e8400-e29b-41d4-a716-446655440000"`
+	Name          string    `json:"name" example:"My Document"`
+	CreatedAt     time.Time `json:"created_at" example:"2025-01-02T15:04:05Z"`
+	UpdatedAt     time.Time `json:"updated_at" example:"2025-01-02T15:04:05Z"`
+	LatestVersion uuid.UUID `json:"latest_version" gorm:"type:char(36);" example:"c3e474u0-e29b-41d4-a716-446655440000"`
 }
 
 func (s *Document) TableName() (res string) {

models/version.go

@@ -7,15 +7,25 @@ import (
 	"github.com/google/uuid"
 )
 
-// Version — конкретная версия документа
+// Version версия документа
+// @Description Version хранит либо патч изменений (Patch), либо полный снимок состояния (Snapshot).
+// @Description Если IsSnapshot=true — Snapshot содержит полное состояние документа, а Patch = null.
+// @Description Если IsSnapshot=false — Patch содержит JSON Patch относительно предыдущей версии.
+// swagger:model Version
 type Version struct {
-	ID         uuid.UUID  `gorm:"type:char(36);primaryKey"`
-	DocumentID uuid.UUID  `gorm:"type:char(36);index"`
-	ParentID   *uuid.UUID `gorm:"type:char(36);"`
-	IsSnapshot bool
-	Patch      json.RawMessage `gorm:"type:json"` // JSON Patch или nil, если Snapshot
-	Snapshot   json.RawMessage `gorm:"type:json"` // Полный JSON, если IsSnapshot = true
-	CreatedAt  time.Time
+	ID         uuid.UUID  `json:"id" gorm:"type:char(36);primaryKey" example:"550e8400-e29b-41d4-a716-446655440001"`
+	DocumentID uuid.UUID  `json:"document_id" gorm:"type:char(36);index" example:"550e8400-e29b-41d4-a716-446655440000"`
+	Document   Document   `json:"-" gorm:"constraint:OnDelete:CASCADE;"`
+	ParentID   *uuid.UUID `json:"parent_id,omitempty" gorm:"type:char(36);" example:"null"`
+	IsSnapshot bool       `json:"is_snapshot" example:"false"`
+
+	// JSON Patch или nil, если Snapshot
+	Patch json.RawMessage `json:"patch,omitempty" gorm:"type:json" example:"[{\"op\":\"replace\",\"path\":\"/name\",\"value\":\"new name\"}]"`
+
+	// Полный JSON, если IsSnapshot = true
+	Snapshot json.RawMessage `json:"snapshot,omitempty" gorm:"type:json" example:"{\"field\": \"value\"}"`
+
+	CreatedAt time.Time `json:"created_at" example:"2025-01-02T15:04:05Z"`
 }
 
 func (s *Version) TableName() (res string) {