feat: 优化文档生成

openapi/generate.go

@@ -147,10 +147,9 @@ func (g *Generate) NewOpenApiDoc(docFlag string, docOption ...OptionFunc) *opena
 	return t
 }
 
-// AddApiDoc 添加接口文档
-func (g *Generate) AddApiDoc(docFlag string, apiMeta define.UriConfig, request any, response any) error {
+// formatType 输入输出数据类型, 转化为统一reflect.Type
+func (g *Generate) formatType(request any, response any) (reflect.Type, reflect.Type) {
 	var (
-		err          error
 		requestType  reflect.Type
 		responseType reflect.Type
 		ok           bool
@@ -170,11 +169,19 @@ func (g *Generate) AddApiDoc(docFlag string, apiMeta define.UriConfig, request a
 			responseType = responseType.Elem()
 		}
 	}
+	return requestType, responseType
+}
 
-	schemaData := GenerateOpenAPISchema(requestType)
-	apiOperate, isRead := g.initApiConfig(docFlag, apiMeta)
-	if isRead {
-		if nil != schemaData {
+// getComponentsSchemaRef 获取组件 schema ref
+func (g *Generate) getComponentsSchemaRef(structKindString string) string {
+	return "#/components/schemas/" + strings.TrimLeft(structKindString, "*")
+}
+
+// setReadRequestParameter 设置读请求参数
+func (g *Generate) setReadRequestParameter(apiOperate *openapi3.Operation, schemaData *openapi3.SchemaRef) {
+	if nil == schemaData {
+		return
+	}
 	for paramName, paramConfig := range schemaData.Value.Properties {
 		apiOperate.Parameters = append(apiOperate.Parameters, &openapi3.ParameterRef{
 			Extensions: nil,
@@ -200,7 +207,9 @@ func (g *Generate) AddApiDoc(docFlag string, apiMeta define.UriConfig, request a
 		})
 	}
 }
-	} else {
+
+// setWriteRequestBody 设置写请求请求 Body
+func (g *Generate) setWriteRequestBody(apiOperate *openapi3.Operation, schemaDataRef string) {
 	apiOperate.RequestBody = &openapi3.RequestBodyRef{
 		Extensions: nil,
 		Origin:     nil,
@@ -217,7 +226,7 @@ func (g *Generate) AddApiDoc(docFlag string, apiMeta define.UriConfig, request a
 					Schema: &openapi3.SchemaRef{
 						Extensions: nil,
 						Origin:     nil,
-							Ref:        "#/components/schemas/" + strings.TrimLeft(requestType.String(), "*"),
+						Ref:        schemaDataRef,
 						Value:      nil,
 					},
 					Example:  nil,
@@ -229,6 +238,20 @@ func (g *Generate) AddApiDoc(docFlag string, apiMeta define.UriConfig, request a
 	}
 }
 
+// AddApiDoc 添加接口文档
+func (g *Generate) AddApiDoc(docFlag string, apiMeta define.UriConfig, request any, response any) error {
+	var (
+		err          error
+		requestType  reflect.Type
+		responseType reflect.Type
+	)
+
+	// 初始化请求数据与响应数据类型
+	requestType, responseType = g.formatType(request, response)
+
+	schemaData := GenerateOpenAPISchema(requestType)
+	apiOperate, isRead := g.initApiConfig(docFlag, apiMeta)
+	if isRead {
 		if g.enableRedundantStorageComponents {
 			// 此处是冗余 components 设置, 便于查看结构体, 不冗余文档也可正常解析
 			requestTypeStr := requestType.String()
@@ -237,6 +260,15 @@ func (g *Generate) AddApiDoc(docFlag string, apiMeta define.UriConfig, request a
 			}
 			// 冗余处理结束
 		}
+		g.setReadRequestParameter(apiOperate, schemaData)
+	} else {
+		requestTypeStr := requestType.String()
+		if _, exist := g.docTable[docFlag].Components.Schemas[requestTypeStr]; !exist {
+			g.docTable[docFlag].Components.Schemas[requestTypeStr] = schemaData
+		}
+		g.setWriteRequestBody(apiOperate, g.getComponentsSchemaRef(requestType.String()))
+	}
+
 	responseTypeStr := responseType.String()
 	if _, exist := g.docTable[docFlag].Components.Schemas[responseTypeStr]; !exist {
 		g.docTable[docFlag].Components.Schemas[responseTypeStr] = GenerateOpenAPISchema(responseType)
@@ -251,7 +283,7 @@ func (g *Generate) AddApiDoc(docFlag string, apiMeta define.UriConfig, request a
 			Content: map[string]*openapi3.MediaType{
 				consts.MimeTypeJson: {
 					Schema: &openapi3.SchemaRef{
-						Ref: "#/components/schemas/" + strings.TrimLeft(responseTypeStr, "*"),
+						Ref: g.getComponentsSchemaRef(responseTypeStr),
 					},
 				},
 			},