From 8230bd47deab168cd628a1715fabc57814aa3fa9 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=E7=99=BD=E8=8C=B6=E6=B8=85=E6=AC=A2?= Date: Wed, 14 Aug 2024 15:43:22 +0800 Subject: [PATCH] save code --- define/generate.go | 22 ++++++++++++++++++++++ define/openapi.go | 2 +- generate.go | 44 ++++++++++++++++++++++++++++++++++++++++++-- 3 files changed, 65 insertions(+), 3 deletions(-) create mode 100644 define/generate.go diff --git a/define/generate.go b/define/generate.go new file mode 100644 index 0000000..daf934e --- /dev/null +++ b/define/generate.go @@ -0,0 +1,22 @@ +// Package define ... +// +// Description : define ... +// +// Author : go_developer@163.com<白茶清欢> +// +// Date : 2024-08-14 15:20 +package define + +// UriBaseConfig 添加接口时的基础配置 +// +// Author : go_developer@163.com<白茶清欢> +// +// Date : 15:21 2024/8/14 +type UriBaseConfig struct { + Uri string `json:"uri"` // 接口路由 + Method string `json:"method"` // 接口请求方法 + ContentType string `json:"content_type"` // 接口请求类型 + TagList []string `json:"tag_list"` // 接口标签列表 + Summary string `json:"summary"` // 接口摘要描述 + Description string `json:"description"` // 接口详细描述 +} diff --git a/define/openapi.go b/define/openapi.go index 084369f..e8da7ae 100644 --- a/define/openapi.go +++ b/define/openapi.go @@ -79,7 +79,7 @@ type PathItemOperationConfig struct { Responses map[string]*Response `json:"responses"` // 描述一个操作可能发生的响应的响应码与响应包含的响应体的对象。default字段可以用来标记一个响应适用于其他未被规范明确定义的HTTP响应码的默认响应。一个Responses 对象必须至少包含一个响应码，而且是成功的响应。 Callbacks map[string]any `json:"callbacks,omitempty"` // 一组相对于父操作的可能出现的回调映射，映射中的每一个键都唯一的映射一个 Callback 对象 Deprecated bool `json:"deprecated"` // 声明此操作已经被废弃，使用者应该尽量避免使用此操作，默认的值是 false。 - Security any `json:"security.o,omitempty"` // 声明那种安全机制可用于此操作。这个列表可以包含多种可用于此操作的安全需求对象，但是在认证一个请求时应该仅使用其中一种。这里的定义会覆盖任何在顶层 security 中的安全声明，因此可以声明一个空数组来变相的移除顶层的安全声明。 + Security any `json:"security,omitempty"` // 声明那种安全机制可用于此操作。这个列表可以包含多种可用于此操作的安全需求对象，但是在认证一个请求时应该仅使用其中一种。这里的定义会覆盖任何在顶层 security 中的安全声明，因此可以声明一个空数组来变相的移除顶层的安全声明。 Servers []*ServerItem `json:"servers,omitempty"` // 一个可用于此操作的额外的 server 数组，这里的定义会覆盖 Path Item 对象 或 顶层的定义。 } diff --git a/generate.go b/generate.go index e6b5c75..e56eff9 100644 --- a/generate.go +++ b/generate.go @@ -10,6 +10,7 @@ package api_doc import ( "git.zhangdeman.cn/gateway/api-doc/define" "git.zhangdeman.cn/zhangdeman/consts" + "reflect" "strings" ) @@ -121,6 +122,45 @@ func (g *Generate) AddServer(serverDomain string, serverDesc string, serverVaria } } -func (g *Generate) AddApi() { - +/** +type PathItemOperationConfig struct { + Tags []string `json:"tags"` // 用于控制API文档的标签列表，标签可以用于在逻辑上分组对资源的操作或作为其它用途的先决条件。 + Summary string `json:"summary"` // 对此操作行为的简短描述。 + Description string `json:"description"` // 对此操作行为的详细解释。CommonMark syntax可以被用来呈现富文本格式. + ExternalDocs *ExternalDocs `json:"externalDocs,omitempty"` // 附加的外部文档。 + OperationID string `json:"operationId"` // 用于标识此操作的唯一字符串，这个id在此API内包含的所有操作中必须是唯一的。相关的工具和库可能会使用此operationId来唯一的标识一个操作，因此推荐在命名时符合一般的编程命名习惯 + Parameters []*PathConfigParameter `json:"parameters,omitempty"` // 定义可用于此操作的参数列表，如果一个同名的参数已经存在于 Path Item，那么这里的定义会覆盖它但是不能移除上面的定义。这个列表不允许包含重复的参数，参数的唯一性由 name 和 location 的组合来确定。这个列表可以使用 Reference 对象 来连接定义于 OpenAPI 对象 components/parameters 的参数。 + RequestBody *RequestBody `json:"requestBody,omitempty"` // 可用于此操作的请求体。requestBody 只能被用于HTTP 1.1 规范 RFC7231 中明确定义了包含请求体的请求方法，在其他没有明确定义的请求方法中，requestBody的消费者应该应该忽略requestBody。 + Responses map[string]*Response `json:"responses"` // 描述一个操作可能发生的响应的响应码与响应包含的响应体的对象。default字段可以用来标记一个响应适用于其他未被规范明确定义的HTTP响应码的默认响应。一个Responses 对象必须至少包含一个响应码，而且是成功的响应。 + Callbacks map[string]any `json:"callbacks,omitempty"` // 一组相对于父操作的可能出现的回调映射，映射中的每一个键都唯一的映射一个 Callback 对象 + Deprecated bool `json:"deprecated"` // 声明此操作已经被废弃，使用者应该尽量避免使用此操作，默认的值是 false。 + Security any `json:"security,omitempty"` // 声明那种安全机制可用于此操作。这个列表可以包含多种可用于此操作的安全需求对象，但是在认证一个请求时应该仅使用其中一种。这里的定义会覆盖任何在顶层 security 中的安全声明，因此可以声明一个空数组来变相的移除顶层的安全声明。 + Servers []*ServerItem `json:"servers,omitempty"` // 一个可用于此操作的额外的 server 数组，这里的定义会覆盖 Path Item 对象 或 顶层的定义。 +} +*/ + +// 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: "这是一份示例基础配置", +// } +// +// parameterPtr : 请求表单结构体实例, 必须为指针, 作用 -> 基于反射生成参数文档 +// +// resultPtr : 返回值结构体实例, 必须为指针, 作用 -> 基于反射生成返回值文档 +func (g *Generate) AddApi(baseCfg *define.UriBaseConfig, parameterPtr any, resultPtr any) error { + paramType := reflect.TypeOf(parameterPtr) + resultType := reflect.TypeOf(resultPtr) + return nil }