feat(net/goai): support OpenAPIv3.1 in description field for schema o…

…bject (#3978)
gogf · Dec 1, 2024 · c1850d4 · c1850d4
1 parent 9923975
commit c1850d4
Show file tree

Hide file tree

Showing 3 changed files with 60 additions and 5 deletions.
diff --git a/net/goai/goai.go b/net/goai/goai.go
@@ -233,6 +233,10 @@ func formatRefToBytes(ref string) []byte {
 	return []byte(fmt.Sprintf(`{"$ref":"#/components/schemas/%s"}`, ref))
 }
 
+func formatRefAndDescToBytes(ref, desc string) []byte {
+	return []byte(fmt.Sprintf(`{"$ref":"#/components/schemas/%s","description":"%s"}`, ref, desc))
+}
+
 func isValidParameterName(key string) bool {
 	return key != "-"
 }
diff --git a/net/goai/goai_shema_ref.go b/net/goai/goai_shema_ref.go
@@ -19,8 +19,9 @@ import (
 type SchemaRefs []SchemaRef
 
 type SchemaRef struct {
-	Ref   string
-	Value *Schema
+	Ref         string
+	Description string
+	Value       *Schema
 }
 
 // isEmbeddedStructDefinition checks and returns whether given golang type is embedded struct definition, like:
@@ -169,6 +170,7 @@ func (oai *OpenApiV3) newSchemaRefWithGolangType(golangType reflect.Type, tagMap
 				}
 				schemaRef.Ref = structTypeName
 				schemaRef.Value = schema
+				schemaRef.Description = schema.Description
 			}
 		}
 	}
@@ -177,7 +179,7 @@ func (oai *OpenApiV3) newSchemaRefWithGolangType(golangType reflect.Type, tagMap
 
 func (r SchemaRef) MarshalJSON() ([]byte, error) {
 	if r.Ref != "" {
-		return formatRefToBytes(r.Ref), nil
+		return formatRefAndDescToBytes(r.Ref, r.Description), nil
 	}
 	return json.Marshal(r.Value)
 }
diff --git a/net/goai/goai_z_unit_issue_test.go b/net/goai/goai_z_unit_issue_test.go
@@ -238,8 +238,8 @@ func Test_Issue3889(t *testing.T) {
 		commonResponseSchema := `{"properties":{"code":{"format":"int","type":"integer"},"data":{"properties":{},"type":"object"},"message":{"format":"string","type":"string"}},"type":"object"}`
 		Status201ExamplesContent := `{"code 1":{"value":{"code":1,"data":"Good","message":"Aha, 201 - 1"}},"code 2":{"value":{"code":2,"data":"Not Bad","message":"Aha, 201 - 2"}}}`
 		Status401ExamplesContent := `{"example 1":{"value":{"code":1,"data":null,"message":"Aha, 401 - 1"}},"example 2":{"value":{"code":2,"data":null,"message":"Aha, 401 - 2"}}}`
-		Status402SchemaContent := `{"$ref":"#/components/schemas/github.com.gogf.gf.v2.net.goai_test.Issue3889Res402"}`
-		Issue3889Res403Ref := `{"$ref":"#/components/schemas/github.com.gogf.gf.v2.net.goai_test.Issue3889Res403"}`
+		Status402SchemaContent := `{"$ref":"#/components/schemas/github.com.gogf.gf.v2.net.goai_test.Issue3889Res402","description":""}`
+		Issue3889Res403Ref := `{"$ref":"#/components/schemas/github.com.gogf.gf.v2.net.goai_test.Issue3889Res403","description":""}`
 
 		t.Assert(j.Get(`paths./default.post.responses.201.content.application/json.examples`).String(), Status201ExamplesContent)
 		t.Assert(j.Get(`paths./default.post.responses.401.content.application/json.examples`).String(), Status401ExamplesContent)
@@ -300,3 +300,52 @@ func Test_Issue3930(t *testing.T) {
 		t.AssertNE(api.Components.Schemas.Get(reqPath).Value.Properties.Get("id"), nil)
 	})
 }
+
+type Issue3235DefaultReq struct {
+	g.Meta `path:"/user/{id}" method:"get" tags:"User" summary:"Get one user"`
+	Id     int64 `v:"required" dc:"user id"`
+}
+type Issue3235DefaultRes struct {
+	Name string         `dc:"test name desc"`
+	User *Issue3235User `dc:"test user desc"`
+}
+type Issue3235User struct {
+	Id uint `json:"id"     orm:"id"     description:"user id"` // user id
+}
+
+type Issue3235 struct{}
+
+func (Issue3235) Default(ctx context.Context, req *Issue3235DefaultReq) (res *Issue3235DefaultRes, err error) {
+	res = &Issue3235DefaultRes{}
+	return
+}
+
+// https://github.com/gogf/gf/issues/3235
+func Test_Issue3235(t *testing.T) {
+	gtest.C(t, func(t *gtest.T) {
+		s := g.Server(guid.S())
+		s.Use(ghttp.MiddlewareHandlerResponse)
+		s.Group("/", func(group *ghttp.RouterGroup) {
+			group.Bind(
+				new(Issue3235),
+			)
+		})
+		s.SetLogger(nil)
+		s.SetOpenApiPath("/api.json")
+		s.SetDumpRouterMap(false)
+		s.Start()
+		defer s.Shutdown()
+
+		time.Sleep(100 * time.Millisecond)
+
+		var (
+			api     = s.GetOpenApi()
+			reqPath = "github.com.gogf.gf.v2.net.goai_test.Issue3235DefaultRes"
+		)
+
+		t.Assert(api.Components.Schemas.Get(reqPath).Value.Properties.Get("Name").Value.Description,
+			"test name desc")
+		t.Assert(api.Components.Schemas.Get(reqPath).Value.Properties.Get("User").Description,
+			"test user desc")
+	})
+}