Skip to content

Commit

Permalink
enhance: support schema example in doc gen (#155)
Browse files Browse the repository at this point in the history
  • Loading branch information
amyXia1994 authored Sep 11, 2023
1 parent 369ae45 commit 8a9c8fa
Show file tree
Hide file tree
Showing 5 changed files with 40 additions and 5 deletions.
18 changes: 16 additions & 2 deletions pkg/tools/gen/genopenapi.go
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down Expand Up @@ -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"`
Expand Down Expand Up @@ -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
Expand Down
9 changes: 7 additions & 2 deletions pkg/tools/gen/templates/doc/schemaDoc.gotmpl
Original file line number Diff line number Diff line change
Expand Up @@ -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 -}}
2 changes: 1 addition & 1 deletion pkg/tools/gen/testdata/doc/pkg/server.k
Original file line number Diff line number Diff line change
Expand Up @@ -22,7 +22,7 @@ schema Server:
See also: kusion_models/core/v1/metadata.k.

Examples
----------------------
--------
myCustomApp = AppConfiguration {
name = "componentName"
}
Expand Down
8 changes: 8 additions & 0 deletions pkg/tools/gen/testdata/doc/pkg/unixlike/md/main.md
Original file line number Diff line number Diff line change
Expand Up @@ -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. -->
8 changes: 8 additions & 0 deletions pkg/tools/gen/testdata/doc/pkg/windows/md/main.md
Original file line number Diff line number Diff line change
Expand Up @@ -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. -->

0 comments on commit 8a9c8fa

Please sign in to comment.