api-doc/define/swagger.go

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

// SwaggerPathConfig ...
//
// Author : zhangdeman001@ke.com<张德满>
//
// Date : 16:16 2024/4/19
type SwaggerPathConfig struct {
	Description string                                `json:"description"` // 接口描述
	Consumes    []string                              `json:"consumes"`    // 请求方式, application/json等
	Produces    []string                              `json:"produces"`    // 请求方式, application/json等
	OperationID string                                `json:"operationId"` // 操作ID
	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"`      // 类型
	Format      string                            `json:"format"`              // 格式化类型
	Description string                            `json:"description"`         // 描述
	Name        string                            `json:"name"`                // 参数名称
	In          string                            `json:"in"`                  // 参数位置
	Required    bool                              `json:"required"`            // 是否必传
	EnumList    []any                             `json:"enum_list,omitempty"` // 枚举值列表
	Schema      *SwaggerPathConfigParameterSchema `json:"schema"`              // 参数schema
}

type SwaggerPathConfigParameterSchema struct {
	Ref string `json:"$ref"` // 引用的数据结构定义
}

// SwaggerPathConfigResponse ...
//
// Author : go_developer@163.com<白茶清欢>
//
// Date : 16:57 2024/4/19
type SwaggerPathConfigResponse struct {
	Description string                           `json:"description"` // 返回值描述
	Schema      *SwaggerPathConfigResponseSchema `json:"schema"`      // 返回值结构
	Ref         string                           `json:"$ref"`        // 引用的数据
}

type SwaggerPathConfigResponseSchema struct {
	Type  string `json:"type"` // 数据类型
	Items struct {
		Ref string `json:"$ref"` // type = array 时, 引用的每一项数据结构
	} `json:"items"`
	Ref string `json:"$ref"` // 引用的数据结构
}

// 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       *SwaggerDefinitionPropertyItem `json:"items,omitempty"`        // 引用类型中的引用(数组)
	AllOf       []map[string]string            `json:"allOf,omitempty"`        // 引用类型中的引用(对象)
	XGoName     string                         `json:"x-go-name,omitempty"`    // go字段名称
	XGoPackage  string                         `json:"x-go-package,omitempty"` // go 包路径
}

// SwaggerDefinitionPropertyItem 属性item兴义
type SwaggerDefinitionPropertyItem struct {
	Type string `json:"type"` // 类型
	Ref  string `json:"$ref"` // 引用
	Enum []any  `json:"enum"` // 枚举值
}

// 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,omitempty"`         // 数据定义
	Responses           map[string]*SwaggerPathConfigResponse    `json:"responses,omitempty"`           // 响应结构列表
	SecurityDefinitions map[string]*SwaggerPathConfigParameter   `json:"securityDefinitions,omitempty"` // 安全选项
}

// 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"` // 是否一定存在
}