api-doc/define/types.go

// Package define ...
//
// Description : define ...
//
// Author : go_developer@163.com<白茶清欢>
//
// Date : 2024-04-19 12:07
package define

// Contact 联系人信息
//
// Author : go_developer@163.com<白茶清欢>
//
// Date : 16:08 2024/4/19
type Contact struct {
	Name  string `json:"name"`  // 姓名
	Url   string `json:"url"`   // 主页地址
	Email string `json:"email"` // 邮箱
}

// License 开源协议
//
// Author : go_developer@163.com<白茶清欢>
//
// Date : 16:09 2024/4/19
type License struct {
	Name string `json:"name"` // 开源协议名
	Url  string `json:"url"`  // 开源协议地址
}

// Info 信息
//
// Author : go_developer@163.com<白茶清欢>
//
// Date : 16:10 2024/4/19
type Info struct {
	Description string  `json:"description"` // 文档描述
	Title       string  `json:"title"`       // 文档标题
	Contact     Contact `json:"contact"`     // 联系方式
	License     License `json:"license"`     // 开源协议
	Version     string  `json:"version"`     // 文档版本
}

// SwaggerPathConfig ...
//
// Author : zhangdeman001@ke.com<张德满>
//
// Date : 16:16 2024/4/19
type SwaggerPathConfig struct {
	Description string                                `json:"description"` // 接口描述
	Consumes    []string                              `json:"consumes"`    // 请求方式, application/json等
	Tags        []string                              `json:"tags"`        // 接口标签
	Summary     string                                `json:"summary"`     // 接口摘要
	Parameters  []*SwaggerPathConfigParameter         `json:"parameters"`  // 参数列表
	Responses   map[string]*SwaggerPathConfigResponse `json:"responses"`   // code码 => 响应描述
}

// SwaggerPathConfigParameter ...
//
// Author : go_developer@163.com<白茶清欢>
//
// Date : 16:53 2024/4/19
type SwaggerPathConfigParameter struct {
	Type        string            `json:"type,omitempty"`      // 类型
	Description string            `json:"description"`         // 描述
	Name        string            `json:"name"`                // 参数名称
	In          string            `json:"in"`                  // 参数位置
	Required    bool              `json:"required"`            // 是否必传
	EnumList    []interface{}     `json:"enum_list,omitempty"` // 枚举值列表
	Schema      map[string]string `json:"schema"`              // 参数schema
}

// SwaggerPathConfigResponse ...
//
// Author : go_developer@163.com<白茶清欢>
//
// Date : 16:57 2024/4/19
type SwaggerPathConfigResponse struct {
	Description string            `json:"description"` // 返回值描述
	Schema      map[string]string `json:"schema"`      // 返回值结构
}

// SwaggerDefinition ...
//
// Author : go_developer@163.com<白茶清欢>
//
// Date : 17:01 2024/4/19
type SwaggerDefinition struct {
	Type       string                                `json:"type"`               // 类型
	Format     string                                `json:"format,omitempty"`   // 原始数据类型
	Required   []string                              `json:"required,omitempty"` // 必传参数列表
	Properties map[string]*SwaggerDefinitionProperty `json:"properties"`         // 参数名 => 参数配置
}

// SwaggerDefinitionProperty ...
//
// Author : go_developer@163.com<白茶清欢>
//
// Date : 17:25 2024/4/19
type SwaggerDefinitionProperty struct {
	Description string              `json:"description"`     // 描述
	Type        string              `json:"type"`            // 类型
	Items       map[string]string   `json:"items,omitempty"` // 引用类型中的引用(数组)
	AllOf       []map[string]string `json:"allOf,omitempty"` // 引用类型中的引用(对象)
}

// Swagger 文档整体结构定义
//
// Author : go_developer@163.com<白茶清欢>
//
// Date : 16:12 2024/4/19
type Swagger struct {
	Schemes     []string                                 `json:"schemes"`
	Swagger     string                                   `json:"swagger"`     // swagger版本 - 2.0
	Host        string                                   `json:"host"`        // 服务域名
	BasePath    string                                   `json:"basePath"`    // 基础path
	Info        Info                                     `json:"info"`        // 文档描述信息
	Paths       map[string]map[string]*SwaggerPathConfig `json:"paths"`       // 接口列表 : 接口 => 请求方法 => 请求配置
	Definitions map[string]*SwaggerDefinition            `json:"definitions"` // 数据定义
}

// SwaggerInput ...
//
// Author : go_developer@163.com<白茶清欢>
//
// Date : 10:18 2024/4/22
type SwaggerInput struct {
	Schemes        []string            `json:"schemes"`          // 协议
	Swagger        string              `json:"swagger"`          // swagger版本 - 2.0
	Host           string              `json:"host"`             // 服务域名
	BasePath       string              `json:"basePath"`         // 基础path
	Info           Info                `json:"info"`             // 文档描述信息
	PathConfigList []*SwaggerPathInput `json:"path_config_list"` // 接口配置列表
}

// SwaggerPathInput 接口配置
//
// Author : go_developer@163.com<白茶清欢>
//
// Date : 10:20 2024/4/22
type SwaggerPathInput struct {
	Uri           string                   `json:"uri"`            // 接口
	Method        string                   `json:"method"`         // 请求方法
	ContentType   string                   `json:"content_type"`   // 请求方式
	Summary       string                   `json:"summary"`        // 摘要
	Description   string                   `json:"description"`    // 描述
	TagList       []string                 `json:"tag_list"`       // 标签列表
	ParameterList []*SwaggerParameterInput `json:"parameter_list"` // 参数列表
	ResponseList  []*SwaggerResponseInput  `json:"response_list"`  // 响应数据
}

type SwaggerResponseInput struct {
	Code        string                      `json:"code"`        // 状态码
	Description string                      `json:"description"` // 描述
	List        []*SwaggerResponseItemInput `json:"list"`        // 数据列表
}

// SwaggerParameterInput ...
//
// Author : go_developer@163.com<白茶清欢>
//
// Date : 10:25 2024/4/22
type SwaggerParameterInput struct {
	Type        string        `json:"type"`                // 类型
	Description string        `json:"description"`         // 描述
	Name        string        `json:"name"`                // 参数名称
	In          string        `json:"in"`                  // 参数位置
	Required    bool          `json:"required"`            // 是否必传
	EnumList    []interface{} `json:"enum_list,omitempty"` // 枚举值列表
}

// SwaggerResponseItemInput 响应数据
//
// Author : go_developer@163.com<白茶清欢>
//
// Date : 10:49 2024/4/22
type SwaggerResponseItemInput struct {
	Type        string `json:"type"`        // 类型
	Description string `json:"description"` // 描述
	Field       string `json:"field"`       // 字段名
	IsRequired  bool   `json:"is_required"` // 是否一定存在
}