From 8a9c8fa1d63310ec08fc5ad4c4032f8605d5b54a Mon Sep 17 00:00:00 2001
From: amyxia <xiarui.xr@antgroup.com>
Date: Mon, 11 Sep 2023 20:44:30 +0800
Subject: [PATCH] enhance: support schema example in doc gen (#155)

---
 pkg/tools/gen/genopenapi.go                    | 18 ++++++++++++++++--
 pkg/tools/gen/templates/doc/schemaDoc.gotmpl   |  9 +++++++--
 pkg/tools/gen/testdata/doc/pkg/server.k        |  2 +-
 .../gen/testdata/doc/pkg/unixlike/md/main.md   |  8 ++++++++
 .../gen/testdata/doc/pkg/windows/md/main.md    |  8 ++++++++
 5 files changed, 40 insertions(+), 5 deletions(-)

diff --git a/pkg/tools/gen/genopenapi.go b/pkg/tools/gen/genopenapi.go
index ca11a711..3a4ee0c8 100644
--- a/pkg/tools/gen/genopenapi.go
+++ b/pkg/tools/gen/genopenapi.go
@@ -68,7 +68,7 @@ type KclOpenAPIType struct {
 	Required             []string                   // list of required schema property names
 	Items                *KclOpenAPIType            // list item type
 	AdditionalProperties *KclOpenAPIType            // dict value type
-	Example              string                     // example
+	Examples             map[string]KclExample      // examples
 	ExternalDocs         string                     // externalDocs
 	KclExtensions        *KclExtensions             // x-kcl- extensions
 	Ref                  string                     // reference to schema path
@@ -97,6 +97,13 @@ const (
 	NumberMultiplier TypeFormat = "units.NumberMultiplier"
 )
 
+// KclExample defines the example code snippet of the schema
+type KclExample struct {
+	Summary     string `json:"summary,omitempty"`
+	Description string `json:"description,omitempty"`
+	Value       string `json:"value,omitempty"`
+}
+
 // KclExtensions defines all the KCL specific extensions patched to OpenAPI
 type KclExtensions struct {
 	XKclModelType   *XKclModelType    `json:"x-kcl-type,omitempty"`
@@ -271,7 +278,14 @@ func GetKclOpenAPIType(pkgPath string, from *kcl.KclType, nested bool) *KclOpenA
 				Type: from.SchemaName,
 			},
 		}
-		// todo newT.Example = from.Examples
+		t.Examples = make(map[string]KclExample, len(from.GetExamples()))
+		for name, example := range from.GetExamples() {
+			t.Examples[name] = KclExample{
+				Summary:     example.Summary,
+				Description: example.Description,
+				Value:       example.Value,
+			}
+		}
 		// todo newT.KclExtensions.XKclDecorators = from.Decorators
 		// todo externalDocs(see also)
 		return &t
diff --git a/pkg/tools/gen/templates/doc/schemaDoc.gotmpl b/pkg/tools/gen/templates/doc/schemaDoc.gotmpl
index e7ccebef..12119dab 100644
--- a/pkg/tools/gen/templates/doc/schemaDoc.gotmpl
+++ b/pkg/tools/gen/templates/doc/schemaDoc.gotmpl
@@ -14,8 +14,13 @@
 
 {{escapeHtml $property.Description $EscapeHtml}}{{end}}
 
-{{end}}{{if ne $Data.Example ""}}#### Examples
+{{end}}{{if ne (len $Data.Examples) 0}}#### Examples
 
-{{$Data.Example}}
+{{range $name, $example := $Data.Examples}}{{if $example.Summary}}**$example.Summary**
+{{end}}{{if $example.Description}}$example.Description
+{{end}}{{if $example.Value}}```
+{{$example.Value}}
+```{{end}}
+{{end}}
 {{end -}}
 {{- end -}}
diff --git a/pkg/tools/gen/testdata/doc/pkg/server.k b/pkg/tools/gen/testdata/doc/pkg/server.k
index e4289894..11b1f34a 100644
--- a/pkg/tools/gen/testdata/doc/pkg/server.k
+++ b/pkg/tools/gen/testdata/doc/pkg/server.k
@@ -22,7 +22,7 @@ schema Server:
         See also: kusion_models/core/v1/metadata.k.
 
     Examples
-    ----------------------
+    --------
     myCustomApp = AppConfiguration {
         name = "componentName"
     }
diff --git a/pkg/tools/gen/testdata/doc/pkg/unixlike/md/main.md b/pkg/tools/gen/testdata/doc/pkg/unixlike/md/main.md
index 72b0c8b8..385dfdea 100644
--- a/pkg/tools/gen/testdata/doc/pkg/unixlike/md/main.md
+++ b/pkg/tools/gen/testdata/doc/pkg/unixlike/md/main.md
@@ -122,4 +122,12 @@ Use this attribute to specify which kind of long-running service you want.
 Valid values: Deployment, CafeDeployment.
 See also: kusion_models/core/v1/workload_metadata.k.
 
+#### Examples
+
+```
+myCustomApp = AppConfiguration {
+    name = "componentName"
+}
+```
+
 <!-- Auto generated by kcl-doc tool, please do not edit. -->
diff --git a/pkg/tools/gen/testdata/doc/pkg/windows/md/main.md b/pkg/tools/gen/testdata/doc/pkg/windows/md/main.md
index bc9346cb..7fda10b6 100644
--- a/pkg/tools/gen/testdata/doc/pkg/windows/md/main.md
+++ b/pkg/tools/gen/testdata/doc/pkg/windows/md/main.md
@@ -122,4 +122,12 @@ Use this attribute to specify which kind of long-running service you want.
 Valid values: Deployment, CafeDeployment.
 See also: kusion_models/core/v1/workload_metadata.k.
 
+#### Examples
+
+```
+myCustomApp = AppConfiguration {
+    name = "componentName"
+}
+```
+
 <!-- Auto generated by kcl-doc tool, please do not edit. -->