From b2ed0db4564dca6a59173c69a6f7eb1d1bf4544b Mon Sep 17 00:00:00 2001 From: Pierre-Emmanuel Jacquier <15922119+pierre-emmanuelJ@users.noreply.github.com> Date: Thu, 7 Dec 2023 12:45:42 +0000 Subject: [PATCH] Add more comments Signed-off-by: Pierre-Emmanuel Jacquier <15922119+pierre-emmanuelJ@users.noreply.github.com> --- v3/generator/client/client.go | 1 + v3/generator/operations/operations.go | 43 ++++++++++--------- .../operations/{method.tmpl => request.tmpl} | 0 v3/generator/schemas/schemas.go | 15 +++++-- 4 files changed, 35 insertions(+), 24 deletions(-) rename v3/generator/operations/{method.tmpl => request.tmpl} (100%) diff --git a/v3/generator/client/client.go b/v3/generator/client/client.go index 066f0f8aa..739dbd335 100644 --- a/v3/generator/client/client.go +++ b/v3/generator/client/client.go @@ -15,6 +15,7 @@ import ( v3 "github.com/pb33f/libopenapi/datamodel/high/v3" ) +// Generate go client from OpenAPI spec servers into a go file. func Generate(doc libopenapi.Document, path, packageName string) error { r, errs := doc.BuildV3Model() for _, err := range errs { diff --git a/v3/generator/operations/operations.go b/v3/generator/operations/operations.go index d74bc502c..35e981a2d 100644 --- a/v3/generator/operations/operations.go +++ b/v3/generator/operations/operations.go @@ -16,6 +16,7 @@ import ( v3 "github.com/pb33f/libopenapi/datamodel/high/v3" ) +// Generate go requests from OpenAPI spec paths operations into a go file. func Generate(doc libopenapi.Document, path, packageName string) error { model, errs := doc.BuildV3Model() for _, err := range errs { @@ -43,8 +44,10 @@ import ( ) `, packageName)) + // Iterate over all paths. err := helpers.ForEachMapSorted(model.Model.Paths.PathItems, func(path string, item any) error { pathItems := item.(*v3.PathItem) + // For each path, render each operations (GET, POST, PUT...etc) schemas and requests. return helpers.ForEachMapSorted(pathItems.GetOperations(), func(opName string, op any) error { operation := op.(*v3.Operation) funcName := helpers.ToCamel(operation.OperationId) @@ -64,22 +67,22 @@ import ( } output.Write(schemaRequest) - schemaParameters, err := renderMethodParameterSchema(funcName, operation) + schemaParameters, err := renderRequestParametersSchema(funcName, operation) if err != nil { return err } output.Write(schemaParameters) - method, err := serializeMethod(path, opName, funcName, operation) + request, err := serializeRequest(path, opName, funcName, operation) if err != nil { return err } - if method == nil { + if request == nil { return nil } - m, err := renderMethod(method) + m, err := renderRequest(request) if err != nil { return err } @@ -178,7 +181,7 @@ func renderRequestSchema(name string, op *v3.Operation) ([]byte, error) { } const queryParamTemplate = ` -func {{ .MethodName }}({{ .ParamName }} {{ .ParamType }}) {{ .MethodReturn }} { +func {{ .FuncName }}({{ .ParamName }} {{ .ParamType }}) {{ .FuncReturn }} { return func(q url.Values) { q.Add("{{ .ParamName }}", fmt.Sprint({{ .ParamName }})) } @@ -186,13 +189,13 @@ func {{ .MethodName }}({{ .ParamName }} {{ .ParamType }}) {{ .MethodReturn }} { ` type QueryParam struct { - MethodName string - ParamName string - ParamType string - MethodReturn string + FuncName string + ParamName string + ParamType string + FuncReturn string } -func renderMethodParameterSchema(name string, op *v3.Operation) ([]byte, error) { +func renderRequestParametersSchema(name string, op *v3.Operation) ([]byte, error) { output := bytes.NewBuffer([]byte{}) query := bytes.NewBuffer([]byte{}) @@ -216,10 +219,10 @@ func renderMethodParameterSchema(name string, op *v3.Operation) ([]byte, error) typ = schemas.RenderSimpleType(s) } if err := t.Execute(query, QueryParam{ - MethodName: name + "With" + helpers.ToCamel(p.Name), - ParamName: helpers.ToLowerCamel(p.Name), - ParamType: typ, - MethodReturn: name + "Opt", + FuncName: name + "With" + helpers.ToCamel(p.Name), + ParamName: helpers.ToLowerCamel(p.Name), + ParamType: typ, + FuncReturn: name + "Opt", }); err != nil { return nil, err } @@ -246,7 +249,7 @@ func renderMethodParameterSchema(name string, op *v3.Operation) ([]byte, error) return output.Bytes(), nil } -type MethodTmpl struct { +type RequestTmpl struct { Comment string Name string Params string @@ -259,10 +262,10 @@ type MethodTmpl struct { QueryParams map[string]string } -func serializeMethod(path, httpMethode, funcName string, op *v3.Operation) (*MethodTmpl, error) { - p := MethodTmpl{ +func serializeRequest(path, httpMethod, funcName string, op *v3.Operation) (*RequestTmpl, error) { + p := RequestTmpl{ Name: funcName, - HTTPMethod: strings.ToUpper(httpMethode), + HTTPMethod: strings.ToUpper(httpMethod), } p.Comment = renderDoc(op) params := getParameters(op, funcName) @@ -298,8 +301,8 @@ func serializeMethod(path, httpMethode, funcName string, op *v3.Operation) (*Met return &p, nil } -func renderMethod(m *MethodTmpl) ([]byte, error) { - t, err := template.New("method.tmpl").ParseFiles("./operations/method.tmpl") +func renderRequest(m *RequestTmpl) ([]byte, error) { + t, err := template.New("request.tmpl").ParseFiles("./operations/request.tmpl") if err != nil { return nil, err } diff --git a/v3/generator/operations/method.tmpl b/v3/generator/operations/request.tmpl similarity index 100% rename from v3/generator/operations/method.tmpl rename to v3/generator/operations/request.tmpl diff --git a/v3/generator/schemas/schemas.go b/v3/generator/schemas/schemas.go index a07254c14..db6a3ba6e 100644 --- a/v3/generator/schemas/schemas.go +++ b/v3/generator/schemas/schemas.go @@ -20,7 +20,7 @@ var ignoredList = map[string]struct{}{ "snapshot-export": {}, } -// Generate go schema models from OpenAPI spec into a go file. +// Generate go models from OpenAPI spec schemas into a go file. func Generate(doc libopenapi.Document, path, packageName string) error { result, errs := doc.BuildV3Model() for _, err := range errs { @@ -122,7 +122,7 @@ func RenderSimpleType(s *base.Schema) string { } // renderSchemaInternal render a given libopenapi Schema into a buffer. -// This function is mostly used recursively to render sub schemas into this buffer. +// This function is mostly used recursively to render sub schemas object into this buffer. // // /!\ for every recusivity call, make sure to check schema reference before, // to prevent end up in infinite loop. @@ -174,7 +174,7 @@ func renderSchemaInternal(schemaName string, s *base.Schema, output *bytes.Buffe output.WriteString(doc) output.WriteString(object) return nil - // map represents an OpenAPI AdditionalProperties, it will always be map[string]Type + // map represents an OpenAPI AdditionalProperties, it will always be map[string]T case "map": output.WriteString(doc) Map, err := renderSimpleMap(schemaName, s, output) @@ -238,6 +238,7 @@ func renderArray(typeName string, s *base.Schema, output *bytes.Buffer) (string, return definition + RenderSimpleType(item), nil } + // Render new object from array schema into the buffer. if err := renderSchemaInternal(typeName, item, output); err != nil { return "", err } @@ -349,6 +350,7 @@ func renderObject(typeName string, s *base.Schema, output *bytes.Buffer) (string } if IsSimpleSchema(prop) { + // Render property type enum. if len(prop.Enum) > 0 { output.WriteString(renderSimpleTypeEnum(typeName+camelName, prop)) definition += camelName + " " + typeName + camelName + tag + "\n" @@ -364,17 +366,20 @@ func renderObject(typeName string, s *base.Schema, output *bytes.Buffer) (string definition += camelName + " " + RenderSimpleType(prop) + tag + "\n" return nil } - definition += camelName + " " + required + RenderSimpleType(prop) + tag + "\n" return nil } + // This is an OpenAPI free form object (deprecated). + // https://docs.42crunch.com/latest/content/oasv3/datavalidation/schema/v3-schema-object-without-properties.htm + // We recommand to use AdditionalProperties instead. if len(prop.Properties) == 0 && prop.AdditionalProperties == nil { definition += camelName + " map[string]any" + tag + "\n" return nil } + // Render additional properties (map). if prop.AdditionalProperties != nil { Map, err := renderSimpleMap(typeName+camelName, prop, output) if err != nil { @@ -384,6 +389,7 @@ func renderObject(typeName string, s *base.Schema, output *bytes.Buffer) (string return nil } + // Render new object from object property into the buffer. if err := renderSchemaInternal(typeName+camelName, prop, output); err != nil { return err } @@ -437,6 +443,7 @@ func renderSimpleMap(typeName string, s *base.Schema, output *bytes.Buffer) (str return definition + RenderSimpleType(addl), nil } + // Render new object from AdditionalProperties schema into the buffer. if err := renderSchemaInternal(typeName, addl, output); err != nil { return "", err }