From 9fba76fd4ec43f60aadd360cca6420765f192410 Mon Sep 17 00:00:00 2001 From: Janos Dobronszki Date: Thu, 28 Jan 2021 13:14:16 +0000 Subject: [PATCH] Docs: Generate client pages (#45) --- cmd/docgen/main.go | 230 +++++++++++++------ docs/hugo-tania/layouts/_default/index.html | 4 +- docs/hugo-tania/layouts/_default/single.html | 15 +- docs/hugo-tania/site/config.yaml | 3 + groups/Makefile | 9 +- groups/proto/groups.pb.go | 4 +- 6 files changed, 187 insertions(+), 78 deletions(-) diff --git a/cmd/docgen/main.go b/cmd/docgen/main.go index f2fde9e..45d6ba6 100644 --- a/cmd/docgen/main.go +++ b/cmd/docgen/main.go @@ -76,13 +76,6 @@ func main() { os.Exit(1) } - contentFile := filepath.Join(workDir, postContentPath, serviceName+".md") - err = ioutil.WriteFile(contentFile, append([]byte("---\ntitle: "+serviceName+"\n---\n"), dat...), 0777) - if err != nil { - fmt.Printf("Failed to write post content to %v:\n%v\n", contentFile, string(outp)) - os.Exit(1) - } - apiJSON := filepath.Join(serviceDir, "api-"+serviceName+".json") js, err := ioutil.ReadFile(apiJSON) if err != nil { @@ -99,7 +92,7 @@ func main() { fmt.Println("Failed to unmarshal", err) os.Exit(1) } - err = saveSpec(contentFile, spec) + err = saveSpec(dat, contentDir, serviceName, spec) if err != nil { fmt.Println("Failed to save to spec file", err) os.Exit(1) @@ -129,68 +122,139 @@ func main() { } } -func saveSpec(filepath string, spec *openapi3.Swagger) error { - fi, err := os.OpenFile(filepath, os.O_APPEND|os.O_WRONLY, os.ModeAppend) - if err != nil { - return err - } - //spec.Paths[0].Parameters[0].MarshalJSON() - //spec.Paths[0].Options - //spec.Paths[0].Post.RequestBody. - tmpl, err := template.New("test").Funcs(template.FuncMap{ - "params": func(p openapi3.Parameters) string { - ls := "" - for _, v := range p { - //if v.Value.In == "body" { - bs, _ := v.MarshalJSON() - ls += string(bs) + ", " - //} - } - return ls - }, - // @todo should take SpecRef here not RequestBodyRef - "schemaJSON": func(ref string) string { - for k, v := range spec.Components.Schemas { - // ie. #/components/requestBodies/PostsSaveRequest contains - // SaveRequest, can't see any other way to correlate - if strings.HasSuffix(ref, k) { - bs, _ := json.MarshalIndent(schemaToMap(v, spec.Components.Schemas), "", " ") - return string(bs) +type specType struct { + name string + tag string + includeReadme bool + filePostFix string + titlePostFix string + template string +} + +var specTypes = []specType{ + { + name: "default markdown", + tag: "Readme", + filePostFix: ".md", + template: defTempl, + includeReadme: true, + }, + { + name: "microjs markdown", + tag: "Micro.js", + filePostFix: "-microjs.md", + titlePostFix: " Micro.js", + template: microJSTempl, + includeReadme: false, + }, +} + +var servicesToTags = map[string][]string{ + "users": []string{"Backend"}, + "helloworld": []string{"Backend"}, + "emails": []string{"Communications"}, + "sms": []string{"Communications"}, + "posts": []string{"Headless CMS"}, + "tags": []string{"Headless CMS"}, + "feeds": []string{"Headless CMS"}, + "chat": []string{"Communications"}, + "geocoding": []string{"Logistics"}, + "places": []string{"Logistics"}, + "routing": []string{"Logistics"}, + "etas": []string{"Logistics"}, + "notes": []string{"Misc"}, + "messages": []string{"Misc"}, +} + +func saveSpec(originalMarkDown []byte, contentDir, serviceName string, spec *openapi3.Swagger) error { + for _, v := range specTypes { + fmt.Println("Processing ", v.name) + contentFile := filepath.Join(contentDir, serviceName+v.filePostFix) + var app []byte + if v.includeReadme { + app = originalMarkDown + } + tags := []string{v.tag} + serviceTags, ok := servicesToTags[serviceName] + if ok { + tags = append(tags, serviceTags...) + } + tagsString := "\n- " + strings.Join(tags, "\n- ") + + err := ioutil.WriteFile(contentFile, append([]byte("---\ntitle: "+serviceName+v.titlePostFix+"\nservicename: "+serviceName+"\nlabels: "+tagsString+"\n---\n"), app...), 0777) + if err != nil { + fmt.Printf("Failed to write post content to %v:\n%v\n", err) + os.Exit(1) + } + fi, err := os.OpenFile(contentFile, os.O_APPEND|os.O_WRONLY, os.ModeAppend) + if err != nil { + return err + } + tmpl, err := template.New("test").Funcs(template.FuncMap{ + "params": func(p openapi3.Parameters) string { + ls := "" + for _, v := range p { + //if v.Value.In == "body" { + bs, _ := v.MarshalJSON() + ls += string(bs) + ", " + //} } - } - - return "Schema related to " + ref + " not found" - - }, - "schemaDescription": func(ref string) string { - for k, v := range spec.Components.Schemas { - // ie. #/components/requestBodies/PostsSaveRequest contains - // SaveRequest, can't see any other way to correlate - if strings.HasSuffix(ref, k) { - return v.Value.Description + return ls + }, + // @todo should take SpecRef here not RequestBodyRef + "schemaJSON": func(prepend int, ref string) string { + for k, v := range spec.Components.Schemas { + // ie. #/components/requestBodies/PostsSaveRequest contains + // SaveRequest, can't see any other way to correlate + if strings.HasSuffix(ref, k) { + bs, _ := json.MarshalIndent(schemaToMap(v, spec.Components.Schemas), "", strings.Repeat(" ", prepend)+" ") + // last line wont get prepended so we fix that here + parts := strings.Split(string(bs), "\n") + // skip if it's only 1 line, ie it's '{}' + if len(parts) <= 1 { + return string(bs) + } + parts[len(parts)-1] = strings.Repeat(" ", prepend) + parts[len(parts)-1] + return strings.Join(parts, "\n") + } } - } - return "Schema related to " + ref + " not found" + return "Schema related to " + ref + " not found" - }, - // turn chat/Chat/History - // to Chat History - "titleize": func(s string) string { - parts := strings.Split(s, "/") - if len(parts) > 2 { - return strings.Join(parts[2:], " ") - } - return strings.Join(parts, " ") - }, - "firstResponseRef": func(rs openapi3.Responses) string { - return rs.Get(200).Ref - }, - }).Parse(templ) - if err != nil { - panic(err) + }, + "schemaDescription": func(ref string) string { + for k, v := range spec.Components.Schemas { + // ie. #/components/requestBodies/PostsSaveRequest contains + // SaveRequest, can't see any other way to correlate + if strings.HasSuffix(ref, k) { + return v.Value.Description + } + } + + return "Schema related to " + ref + " not found" + }, + // turn chat/Chat/History + // to Chat History + "titleize": func(s string) string { + parts := strings.Split(s, "/") + if len(parts) > 2 { + return strings.Join(parts[2:], " ") + } + return strings.Join(parts, " ") + }, + "firstResponseRef": func(rs openapi3.Responses) string { + return rs.Get(200).Ref + }, + }).Parse(v.template) + if err != nil { + panic(err) + } + err = tmpl.Execute(fi, spec) + if err != nil { + return err + } } - return tmpl.Execute(fi, spec) + return nil } func schemaToMap(spec *openapi3.SchemaRef, schemas map[string]*openapi3.SchemaRef) map[string]interface{} { @@ -226,7 +290,7 @@ func schemaToMap(spec *openapi3.SchemaRef, schemas map[string]*openapi3.SchemaRe return recurse(spec.Value.Properties) } -const templ = ` +const defTempl = ` ## cURL {{ range $key, $value := .Paths }} @@ -238,9 +302,39 @@ being lifted correctly from the proto by the openapi spec generator --> > curl 'https://api.m3o.com{{ $key }}' \ -H 'micro-namespace: $yourNamespace' \ -H 'authorization: Bearer $yourToken' \ - -d {{ $value.Post.RequestBody.Ref | schemaJSON }}; + -d {{ $value.Post.RequestBody.Ref | schemaJSON 0 }}; # Response -{{ $value.Post.Responses | firstResponseRef | schemaJSON }} +{{ $value.Post.Responses | firstResponseRef | schemaJSON 0 }} +` + "```" + ` + +{{ end }} +` + +const microJSTempl = ` +## Micro.js + +{{ range $key, $value := .Paths }} +### {{ $key | titleize }} + +{{ $value.Post.RequestBody.Ref | schemaDescription }} +` + "```" + `html + + ` + "```" + ` {{ end }} diff --git a/docs/hugo-tania/layouts/_default/index.html b/docs/hugo-tania/layouts/_default/index.html index 844f7f6..dfdaa92 100644 --- a/docs/hugo-tania/layouts/_default/index.html +++ b/docs/hugo-tania/layouts/_default/index.html @@ -27,11 +27,11 @@ {{ $pages := where .Site.RegularPages "Type" "in" .Site.Params.mainSections }} {{ $projects := where .Site.RegularPages "Section" "projects" }} -{{ $pages = first (default 100 .Site.Params.homePosts) (sort (where .Site.RegularPages "Type" "in" .Site.Params.mainSections) "Date" "desc") }}
+ {{ $pages = .Site.Taxonomies.labels.readme }} {{ range $i,$e := $pages }} {{if modBool $i 2}} @@ -58,6 +58,8 @@ {{ end }} {{ end }} + +
{{ if gt (len $projects) 0}} diff --git a/docs/hugo-tania/layouts/_default/single.html b/docs/hugo-tania/layouts/_default/single.html index 72354a2..effcd22 100644 --- a/docs/hugo-tania/layouts/_default/single.html +++ b/docs/hugo-tania/layouts/_default/single.html @@ -5,18 +5,23 @@
-

{{ .Title }}

+

{{ .Params.servicename }}

- API Spec + Readme   - Source + Micro.js +   + API Spec +   + Source
+
+ -->
- {{ range (.GetTerms "tags") }} + {{ range (.GetTerms "labels") }} {{ .LinkTitle }} {{ end }}
diff --git a/docs/hugo-tania/site/config.yaml b/docs/hugo-tania/site/config.yaml index 0c4be91..7c62508 100644 --- a/docs/hugo-tania/site/config.yaml +++ b/docs/hugo-tania/site/config.yaml @@ -30,3 +30,6 @@ markup: permalinks: post: /:filename + +taxonomies: + tag: "labels" \ No newline at end of file diff --git a/groups/Makefile b/groups/Makefile index 43d931e..fc2aeff 100644 --- a/groups/Makefile +++ b/groups/Makefile @@ -7,8 +7,13 @@ init: go get github.com/micro/micro/v3/cmd/protoc-gen-micro .PHONY: proto proto: - protoc --proto_path=. --micro_out=. --go_out=:. proto/groups.proto - + protoc --openapi_out=. --proto_path=. --micro_out=. --go_out=:. proto/groups.proto + +.PHONY: docs +docs: + protoc --openapi_out=. --proto_path=. --micro_out=. --go_out=:. proto/groups.proto + @redoc-cli bundle api-groups.json + .PHONY: build build: go build -o groups *.go diff --git a/groups/proto/groups.pb.go b/groups/proto/groups.pb.go index d7844b1..5a4b734 100644 --- a/groups/proto/groups.pb.go +++ b/groups/proto/groups.pb.go @@ -1,7 +1,7 @@ // Code generated by protoc-gen-go. DO NOT EDIT. // versions: -// protoc-gen-go v1.23.0 -// protoc v3.13.0 +// protoc-gen-go v1.25.0 +// protoc v3.6.1 // source: proto/groups.proto package groups