zhangdeman/api-doc
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

升级文档基础配置项处理, 固定值配置化 #22

Merged
zhangdeman merged 5 commits from feature/upgrade into master 2025-08-23 10:54:33 +08:00
Conversation 0 Commits 5 Files Changed 40 +214 -311
20 changed files with 214 additions and 311 deletions
Download Patch File Download Diff File Expand all files Collapse all files
Showing only changes of commit 90ca1f853f - Show all commits

92
define/openapi.go
View File

@ -8,10 +8,6 @@
package define package define
// OpenapiDoc openapi文档结构, 文档规范参见 : https://openapi.apifox.cn/ // OpenapiDoc openapi文档结构, 文档规范参见 : https://openapi.apifox.cn/
//
// Author : go_developer@163.com<白茶清欢>
//
// Date : 12:16 2024/7/19
type OpenapiDoc struct { type OpenapiDoc struct {
Openapi string `json:"openapi" required:"true"` // 必选. 这个字符串必须是开放 API 规范版本号提到的符合语义化版本号规范的版本号。openapi字段应该被工具或者客户端用来解释 OpenAPI 文档. Openapi string `json:"openapi" required:"true"` // 必选. 这个字符串必须是开放 API 规范版本号提到的符合语义化版本号规范的版本号。openapi字段应该被工具或者客户端用来解释 OpenAPI 文档.
Info *Info `json:"info,omitempty" required:"true"` // 必选。此字段提供 API 相关的元数据。相关工具可能需要这个字段。 Info *Info `json:"info,omitempty" required:"true"` // 必选。此字段提供 API 相关的元数据。相关工具可能需要这个字段。
@ -22,19 +18,11 @@ type OpenapiDoc struct {
} }
// Components 数据结构定义 // Components 数据结构定义
//
// Author : go_developer@163.com<白茶清欢>
//
// Date : 21:22 2024/7/19
type Components struct { type Components struct {
Schemas map[string]*Schema `json:"schemas"` // 数据结构定义 Schemas map[string]*Schema `json:"schemas"` // 数据结构定义
} }
// PathConfig ... // PathConfig ...
//
// Author : go_developer@163.com<白茶清欢>
//
// Date : 18:06 2024/7/19
type PathConfig struct { type PathConfig struct {
Get *PathItemOperationConfig `json:"get,omitempty"` // 定义适用于此路径的 GET 操作。 Get *PathItemOperationConfig `json:"get,omitempty"` // 定义适用于此路径的 GET 操作。
Put *PathItemOperationConfig `json:"put,omitempty"` // 定义适用于此路径的 PUT 操作。 Put *PathItemOperationConfig `json:"put,omitempty"` // 定义适用于此路径的 PUT 操作。
@ -51,10 +39,6 @@ type PathConfig struct {
// 描述对一个路径可执行的有效操作。 // 描述对一个路径可执行的有效操作。
// 依赖与 ACL constraints 的设置，一个Path Item可以是一个空对象， // 依赖与 ACL constraints 的设置，一个Path Item可以是一个空对象，
// 文档的读者仍然可以看到这个路径，但是他们将无法了解到对这个路径可用的任何操作和参数。 // 文档的读者仍然可以看到这个路径，但是他们将无法了解到对这个路径可用的任何操作和参数。
//
// Author : go_developer@163.com<白茶清欢>
//
// Date : 12:22 2024/7/19
type PathItemConfig struct { type PathItemConfig struct {
Ref string `json:"$ref"` // 指定对此路径的外部定义的引用，引用的格式必须符合 Path Item 对象 的格式，如果引用的外部定义和此对象内的其他定义有冲突，该如何处理冲突尚未被定义。 Ref string `json:"$ref"` // 指定对此路径的外部定义的引用，引用的格式必须符合 Path Item 对象 的格式，如果引用的外部定义和此对象内的其他定义有冲突，该如何处理冲突尚未被定义。
Summary string `json:"summary"` // 一个可选的简要总结字符串，用来描述此路径内包含的所有操作。 Summary string `json:"summary"` // 一个可选的简要总结字符串，用来描述此路径内包含的所有操作。
@ -65,10 +49,6 @@ type PathItemConfig struct {
} }
// PathItemOperationConfig 描述对路径的某个操作。 // PathItemOperationConfig 描述对路径的某个操作。
//
// Author : go_developer@163.com<白茶清欢>
//
// Date : 16:20 2024/7/19
type PathItemOperationConfig struct { type PathItemOperationConfig struct {
Tags []string `json:"tags"` // 用于控制API文档的标签列表，标签可以用于在逻辑上分组对资源的操作或作为其它用途的先决条件。 Tags []string `json:"tags"` // 用于控制API文档的标签列表，标签可以用于在逻辑上分组对资源的操作或作为其它用途的先决条件。
Summary string `json:"summary"` // 对此操作行为的简短描述。 Summary string `json:"summary"` // 对此操作行为的简短描述。
@ -85,20 +65,12 @@ type PathItemOperationConfig struct {
} }
// ExternalDocs 外部文档配置 // ExternalDocs 外部文档配置
//
// Author : go_developer@163.com<白茶清欢>
//
// Date : 16:30 2024/7/19
type ExternalDocs struct { type ExternalDocs struct {
Url string `json:"url"` // 必选. 外部文档的URL地址，这个值必须是URL地址格式。 Url string `json:"url"` // 必选. 外部文档的URL地址，这个值必须是URL地址格式。
Description string `json:"description"` // 对引用的外部文档的简短描述。CommonMark syntax可以被用来呈现富文本格式. Description string `json:"description"` // 对引用的外部文档的简短描述。CommonMark syntax可以被用来呈现富文本格式.
} }
// PathConfigParameter 参数配置 // PathConfigParameter 参数配置
//
// Author : go_developer@163.com<白茶清欢>
//
// Date : 12:29 2024/7/19
type PathConfigParameter struct { type PathConfigParameter struct {
Name string `json:"name"` // 参数名称 Name string `json:"name"` // 参数名称
In string `json:"in"` // 必选. 参数的位置，可能的值有 "query", "header", "path" 或 "cookie"。 In string `json:"in"` // 必选. 参数的位置，可能的值有 "query", "header", "path" 或 "cookie"。
@ -114,10 +86,6 @@ type PathConfigParameter struct {
} }
// Schema ... // Schema ...
//
// Author : go_developer@163.com<白茶清欢>
//
// Date : 12:32 2024/7/19
type Schema struct { type Schema struct {
Nullable bool `json:"nullable,omitempty"` // 对于定义的schema，允许发送 null 值。默认值是 false. Nullable bool `json:"nullable,omitempty"` // 对于定义的schema，允许发送 null 值。默认值是 false.
Discriminator *SchemaDiscriminator `json:"discriminator,omitempty"` // 说白了, 就是一个字段可能是不同的数据结构。。。 Discriminator *SchemaDiscriminator `json:"discriminator,omitempty"` // 说白了, 就是一个字段可能是不同的数据结构。。。
@ -145,10 +113,6 @@ type Schema struct {
} }
// Property 是从 JSON Schema 提取出来的，但是做了一些调整以适应 OpenAPI Specification。 // Property 是从 JSON Schema 提取出来的，但是做了一些调整以适应 OpenAPI Specification。
//
// Author : go_developer@163.com<白茶清欢>
//
// Date : 17:05 2024/7/19
type Property struct { type Property struct {
Type any `json:"type,omitempty"` // 数据类型(string | []string), swagger本身的定义 Type any `json:"type,omitempty"` // 数据类型(string | []string), swagger本身的定义
Format string `json:"format,omitempty"` // 对应编程语言中的数据类型描述 Format string `json:"format,omitempty"` // 对应编程语言中的数据类型描述
@ -171,10 +135,6 @@ type Property struct {
} }
// PropertyXOf ... // PropertyXOf ...
//
// Author : go_developer@163.com<白茶清欢>
//
// Date : 17:13 2024/7/19
type PropertyXOf struct { type PropertyXOf struct {
Type string `json:"type,omitempty"` // 基础类型 Type string `json:"type,omitempty"` // 基础类型
Format string `json:"format,omitempty"` // 真实类型 Format string `json:"format,omitempty"` // 真实类型
@ -186,20 +146,12 @@ type PropertyXOf struct {
// SchemaDiscriminator 当一个 request bodies 或 response payloads 可以是多种 schemas 时，可以使用一个 discriminator 对象来帮助序列化、反序列化和校验 // SchemaDiscriminator 当一个 request bodies 或 response payloads 可以是多种 schemas 时，可以使用一个 discriminator 对象来帮助序列化、反序列化和校验
// discriminator 属性仅在与 oneOf, anyOf, allOf 这几个复合关键字之一一起使用时才合法. // discriminator 属性仅在与 oneOf, anyOf, allOf 这几个复合关键字之一一起使用时才合法.
//
// Author : go_developer@163.com<白茶清欢>
//
// Date : 16:48 2024/7/19
type SchemaDiscriminator struct { type SchemaDiscriminator struct {
PropertyName string `json:"propertyName"` // 必选. 在 payload 中表示 discriminator 值的属性的名称。 PropertyName string `json:"propertyName"` // 必选. 在 payload 中表示 discriminator 值的属性的名称。
Mapping map[string]string `json:"mapping"` // 一个映射 payload 中的值和 schema 名称或引用的对象。 Mapping map[string]string `json:"mapping"` // 一个映射 payload 中的值和 schema 名称或引用的对象。
} }
// XML 一个为 XML 模型定义微调过的元数据对象。 // XML 一个为 XML 模型定义微调过的元数据对象。
//
// Author : go_developer@163.com<白茶清欢>
//
// Date : 16:56 2024/7/19
type XML struct { type XML struct {
Name string `json:"name"` // 替换用于描述元素/属性的结构特性的名称。当在 items 内定义时将会影响处于此列表中的每个元素的名称。当定义于 items 之上时将会影响它说包裹的元素且仅当 wrapped 是 true 时，如果 wrapped 是 false 时它将会被忽略 Name string `json:"name"` // 替换用于描述元素/属性的结构特性的名称。当在 items 内定义时将会影响处于此列表中的每个元素的名称。当定义于 items 之上时将会影响它说包裹的元素且仅当 wrapped 是 true 时，如果 wrapped 是 false 时它将会被忽略
Namespace string `json:"namespace"` // 命名空间定义的 URI。其值必须是绝对 URI。 Namespace string `json:"namespace"` // 命名空间定义的 URI。其值必须是绝对 URI。
@ -209,10 +161,6 @@ type XML struct {
} }
// RequestBody 定义请求体 // RequestBody 定义请求体
//
// Author : go_developer@163.com<白茶清欢>
//
// Date : 17:17 2024/7/19
type RequestBody struct { type RequestBody struct {
Required bool `json:"required"` // 指定请求体是不是应该被包含在请求中，默认值是false。 Required bool `json:"required"` // 指定请求体是不是应该被包含在请求中，默认值是false。
Description string `json:"description,omitempty"` // 对请求体的简要描述，可以包含使用示例，CommonMark syntax可以被用来呈现富文本格式 Description string `json:"description,omitempty"` // 对请求体的简要描述，可以包含使用示例，CommonMark syntax可以被用来呈现富文本格式
@ -221,10 +169,6 @@ type RequestBody struct {
} }
// Media 本质即为不一样 content_type 对应的数据结构定义 // Media 本质即为不一样 content_type 对应的数据结构定义
//
// Author : go_developer@163.com<白茶清欢>
//
// Date : 17:21 2024/7/19
type Media struct { type Media struct {
Schema *Schema `json:"schema,omitempty"` // 定义此媒体类型的结构。 Schema *Schema `json:"schema,omitempty"` // 定义此媒体类型的结构。
Example map[string]any `json:"example,omitempty"` // 媒体类型的示例。示例对象应该符合此媒体类型的格式， 这里指定的example对象 object is mutually exclusive of the examples object. 而且如果引用的schema也包含示例，在这里指定的example值将会覆盖schema提供的示例。 Example map[string]any `json:"example,omitempty"` // 媒体类型的示例。示例对象应该符合此媒体类型的格式， 这里指定的example对象 object is mutually exclusive of the examples object. 而且如果引用的schema也包含示例，在这里指定的example值将会覆盖schema提供的示例。
@ -233,10 +177,6 @@ type Media struct {
} }
// Encoding 一个编码定义仅适用于一个结构属性 // Encoding 一个编码定义仅适用于一个结构属性
//
// Author : go_developer@163.com<白茶清欢>
//
// Date : 17:28 2024/7/19
type Encoding struct { type Encoding struct {
ContentType string `json:"content_type,omitempty"` // 对具体属性的 Content-Type的编码。默认值取决于属性的类型：application/octet-stream编码适用于binary格式的string；text/plain适用于其他原始值；application/json适用于object；对于array值类型的默认值取决于数组内元素的类型，默认值可以是明确的媒体类型(比如application/json), 或者通配符类型的媒体类型(比如image/*), 又或者是用分号分隔的两种媒体类型。 ContentType string `json:"content_type,omitempty"` // 对具体属性的 Content-Type的编码。默认值取决于属性的类型：application/octet-stream编码适用于binary格式的string；text/plain适用于其他原始值；application/json适用于object；对于array值类型的默认值取决于数组内元素的类型，默认值可以是明确的媒体类型(比如application/json), 或者通配符类型的媒体类型(比如image/*), 又或者是用分号分隔的两种媒体类型。
Headers map[string]*Header `json:"headers,omitempty"` // 提供附加信息的请求头键值对映射。比如Content-Disposition、Content-Type各自描述了不同的信息而且在这里将会被忽略，如果请求体的媒体类型不是multipart，这个属性将会被忽略。 Headers map[string]*Header `json:"headers,omitempty"` // 提供附加信息的请求头键值对映射。比如Content-Disposition、Content-Type各自描述了不同的信息而且在这里将会被忽略，如果请求体的媒体类型不是multipart，这个属性将会被忽略。
@ -257,10 +197,6 @@ type Encoding struct {
type Header PathConfigParameter type Header PathConfigParameter
// Example ... // Example ...
//
// Author : go_developer@163.com<白茶清欢>
//
// Date : 17:24 2024/7/19
type Example struct { type Example struct {
Summary string `json:"summary,omitempty"` // example 的简要描述。 Summary string `json:"summary,omitempty"` // example 的简要描述。
Description string `json:"description,omitempty"` // example 的详细描述。CommonMark syntax可以被用来呈现富文本格式. Description string `json:"description,omitempty"` // example 的详细描述。CommonMark syntax可以被用来呈现富文本格式.
@ -269,10 +205,6 @@ type Example struct {
} }
// Response 响应的数据结构 // Response 响应的数据结构
//
// Author : go_developer@163.com<白茶清欢>
//
// Date : 17:38 2024/7/19
type Response struct { type Response struct {
Description string `json:"description" required:"true"` // 必选. 对响应的简短描述。CommonMark syntax可以被用来呈现富文本格式. Description string `json:"description" required:"true"` // 必选. 对响应的简短描述。CommonMark syntax可以被用来呈现富文本格式.
Headers map[string]*Header `json:"headers,omitempty"` // 映射HTTP头名称到其定义。RFC7230 规定了HTTP头名称不区分大小写。如果一个响应头使用"Content-Type"作为HTTP头名称，它会被忽略。 Headers map[string]*Header `json:"headers,omitempty"` // 映射HTTP头名称到其定义。RFC7230 规定了HTTP头名称不区分大小写。如果一个响应头使用"Content-Type"作为HTTP头名称，它会被忽略。
@ -281,10 +213,6 @@ type Response struct {
} }
// Info 信息 // Info 信息
//
// Author : go_developer@163.com<白茶清欢>
//
// Date : 16:10 2024/4/19
type Info struct { type Info struct {
Description string `json:"description,omitempty"` // 对应用的简短描述。 CommonMark syntax 可以被用来表示富文本呈现。 Description string `json:"description,omitempty"` // 对应用的简短描述。 CommonMark syntax 可以被用来表示富文本呈现。
Title string `json:"title,omitempty" required:"true"` // 必选. 应用的名称。 Title string `json:"title,omitempty" required:"true"` // 必选. 应用的名称。
@ -295,10 +223,6 @@ type Info struct {
} }
// Contact 联系人信息 // Contact 联系人信息
//
// Author : go_developer@163.com<白茶清欢>
//
// Date : 16:08 2024/4/19
type Contact struct { type Contact struct {
Name string `json:"name,omitempty"` // 人或组织的名称。 Name string `json:"name,omitempty"` // 人或组织的名称。
Url string `json:"url,omitempty"` // 指向联系人信息的 URL 地址，必须是 URL 地址格式。 Url string `json:"url,omitempty"` // 指向联系人信息的 URL 地址，必须是 URL 地址格式。
@ -306,20 +230,12 @@ type Contact struct {
} }
// License 开源协议 // License 开源协议
//
// Author : go_developer@163.com<白茶清欢>
//
// Date : 16:09 2024/4/19
type License struct { type License struct {
Name string `json:"name,omitempty"` // 开源协议名 Name string `json:"name,omitempty"` // 开源协议名
Url string `json:"url,omitempty"` // 开源协议地址 Url string `json:"url,omitempty"` // 开源协议地址
} }
// ServerItem server 对象结构 // ServerItem server 对象结构
//
// Author : go_developer@163.com<白茶清欢>
//
// Date : 14:18 2024/7/19
type ServerItem struct { type ServerItem struct {
Url string `json:"url,omitempty" required:"true"` // 必选. 指向目标主机的 URL 地址。这个 URL 地址支持服务器变量而且可能是相对路径，表示主机路径是相对于本文档所在的路径。当一个变量被命名为类似{brackets}时需要替换此变量。 Url string `json:"url,omitempty" required:"true"` // 必选. 指向目标主机的 URL 地址。这个 URL 地址支持服务器变量而且可能是相对路径，表示主机路径是相对于本文档所在的路径。当一个变量被命名为类似{brackets}时需要替换此变量。
Description string `json:"description,omitempty"` // 一个可选的字符串，用来描述此 URL 地址。CommonMark syntax可以被用来呈现富文本格式. Description string `json:"description,omitempty"` // 一个可选的字符串，用来描述此 URL 地址。CommonMark syntax可以被用来呈现富文本格式.
@ -327,10 +243,6 @@ type ServerItem struct {
} }
// ServerItemVariable ... // ServerItemVariable ...
//
// Author : go_developer@163.com<白茶清欢>
//
// Date : 14:22 2024/7/19
type ServerItemVariable struct { type ServerItemVariable struct {
Default string `json:"default,omitempty"` // 变量默认值 Default string `json:"default,omitempty"` // 变量默认值
Description string `json:"description,omitempty"` // 变量描述 Description string `json:"description,omitempty"` // 变量描述
@ -338,10 +250,6 @@ type ServerItemVariable struct {
} }
// TagItem 每一个标签数据结构 // TagItem 每一个标签数据结构
//
// Author : go_developer@163.com<白茶清欢>
//
// Date : 12:18 2024/7/19
type TagItem struct { type TagItem struct {
Name string `json:"name,omitempty"` // 标签名称 Name string `json:"name,omitempty"` // 标签名称
Description string `json:"description,omitempty"` // 标签描述 Description string `json:"description,omitempty"` // 标签描述

66
generate.go
View File

@ -84,45 +84,7 @@ func (g *Generate) Doc() *define.OpenapiDoc {
return g.docData return g.docData
} }
// SetLicense 设置文档协议
//
// Author : go_developer@163.com<白茶清欢>
//
// Date : 14:56 2024/8/14
func (g *Generate) SetLicense(name string, url string) {
g.docData.Info.License.Name = name
g.docData.Info.License.Url = url
}
// AddTag 新增tag
//
// Author : go_developer@163.com<白茶清欢>
//
// Date : 14:23 2024/8/14
func (g *Generate) AddTag(tagName string, tagDesc string) {
isHasTag := false
for _, item := range g.docData.Tags {
if item.Name == tagName {
if len(tagDesc) > 0 {
item.Description = tagDesc
}
isHasTag = true
break
}
}
if !isHasTag {
g.docData.Tags = append(g.docData.Tags, &define.TagItem{
Name: tagName,
Description: tagDesc,
})
}
}
// AddServer 添加server // AddServer 添加server
//
// Author : go_developer@163.com<白茶清欢>
//
// Date : 14:45 2024/8/14
func (g *Generate) AddServer(serverDomain string, serverDesc string, serverVariable map[string]*define.ServerItemVariable) { func (g *Generate) AddServer(serverDomain string, serverDesc string, serverVariable map[string]*define.ServerItemVariable) {
if nil == serverVariable { if nil == serverVariable {
serverVariable = make(map[string]*define.ServerItemVariable) serverVariable = make(map[string]*define.ServerItemVariable)
@ -151,35 +113,7 @@ func (g *Generate) AddServer(serverDomain string, serverDesc string, serverVaria
} }
} }
// AddApi 新增Api
//
// Author : go_developer@163.com<白茶清欢>
//
// Date : 15:04 2024/8/14
//
// baseCfg : 接口基础配置, 示例数据
//
// &define.UriBaseConfig{
// Uri: "/foo/bar",
// Method: http.MethodPost,
// ContentType: ["application/json"],
// TagList: []string{"测试标签"},
// Summary: "这是一份示例基础配置",
// Description: "这是一份示例基础配置",
// }
//
// paramList : 参数列表
//
// resultList : 返回值列表
func (g *Generate) AddApi(baseCfg *define.UriBaseConfig, paramList []*define.ParamConfig, resultList []*define.ResultConfig) error {
return nil
}
// AddApiFromInAndOut 通过请求参数的 // AddApiFromInAndOut 通过请求参数的
//
// Author : go_developer@163.com<白茶清欢>
//
// Date : 14:22 2025/2/9
func (g *Generate) AddApiFromInAndOut(uriPrefix string, paramType reflect.Type, resultType reflect.Type) error { func (g *Generate) AddApiFromInAndOut(uriPrefix string, paramType reflect.Type, resultType reflect.Type) error {
if paramType.Kind() == reflect.Ptr { if paramType.Kind() == reflect.Ptr {
paramType = paramType.Elem() paramType = paramType.Elem()