feat: docs api design

internal/schema/base.go

@@ -0,0 +1,106 @@
+package schema
+
+const (
+	maxPageSize     = 1000
+	defaultPageSize = 10
+)
+
+type PageableQuery struct {
+	Size   *int `query:"size"   oai:"description=返回数据数量;default=10;maximum=1000"`
+	Offset *int `query:"offset" oai:"description=数据偏移量;default=0"`
+}
+
+func (p *PageableQuery) GetLimit() int {
+	if p.Size == nil {
+		return defaultPageSize
+	}
+	if *p.Size >= maxPageSize {
+		return maxPageSize
+	}
+	return *p.Size
+}
+
+func (p *PageableQuery) GetOffset() int {
+	if p.Offset == nil {
+		return 0
+	}
+	return *p.Offset
+}
+
+type SortField struct {
+	Field string
+	Asc   bool
+}
+type SortableQuery struct {
+	SortBy *[]string `query:"sort_by" oai:"description=排序字段, 如: +id,-created_at,test 表示依次按照id正序,created_at倒序,test正序"`
+}
+
+func (s *SortableQuery) GetOrderField() []SortField {
+	if s.SortBy == nil {
+		return nil
+	}
+	fields := make([]SortField, 0, len(*s.SortBy))
+	for _, v := range *s.SortBy {
+		if v == "" {
+			continue
+		}
+		switch v[0] {
+		case '+':
+			fields = append(fields, SortField{Field: v[1:], Asc: true})
+		case '-':
+			fields = append(fields, SortField{Field: v[1:], Asc: false})
+		default:
+			fields = append(fields, SortField{Field: v, Asc: true})
+		}
+	}
+
+	return fields
+}
+
+type SortableBody struct {
+	SortBy *[]string `json:"sort_by" oai:"description=排序字段, 如: id desc/asc"`
+}
+
+func (s *SortableBody) GetOrderField() []SortField {
+	if s.SortBy == nil {
+		return nil
+	}
+	fields := make([]SortField, 0, len(*s.SortBy))
+	for _, v := range *s.SortBy {
+		if v == "" {
+			continue
+		}
+		switch v[0] {
+		case '+':
+			fields = append(fields, SortField{Field: v[1:], Asc: true})
+		case '-':
+			fields = append(fields, SortField{Field: v[1:], Asc: false})
+		default:
+			fields = append(fields, SortField{Field: v, Asc: true})
+		}
+	}
+
+	return fields
+}
+
+type PageableBody struct {
+	Size   *int `json:"size"   oai:"description=返回数据数量;default=10;maximum=1000"`
+	Offset *int `json:"offset" oai:"description=数据偏移量;default=0"`
+}
+
+func (p *PageableBody) GetLimit() int {
+	if p.Size == nil {
+		return defaultPageSize
+	}
+	if *p.Size >= maxPageSize {
+		return maxPageSize
+	}
+	return *p.Size
+}
+
+func (p *PageableBody) GetOffset() int {
+	if p.Offset == nil {
+		return 0
+	}
+	return *p.Offset
+}