mirror of
https://github.com/kevin-DL/services.git
synced 2026-01-18 05:35:10 +00:00
Docs: Generate client pages (#45)
This commit is contained in:
Janos Dobronszki
@@ -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 }}
|
||||
<!-- We use the request body description here as endpoint descriptions are not
|
||||
being lifted correctly from the proto by the openapi spec generator -->
|
||||
{{ $value.Post.RequestBody.Ref | schemaDescription }}
|
||||
` + "```" + `html
|
||||
<script src="https://web.m3o.com/assets/micro.js"></script>
|
||||
<script type="text/javascript">
|
||||
document.addEventListener("DOMContentLoaded", function (event) {
|
||||
// Login is only required for endpoints doing authorization
|
||||
Micro.requireLogin(function () {
|
||||
Micro.post(
|
||||
"{{ $key }}",
|
||||
"micro",
|
||||
{{ $value.Post.RequestBody.Ref | schemaJSON 8 }},
|
||||
function (data) {
|
||||
console.log("Success.");
|
||||
}
|
||||
);
|
||||
});
|
||||
});
|
||||
</script>
|
||||
` + "```" + `
|
||||
|
||||
{{ end }}
|
||||
|
||||
Reference in New Issue
Block a user