goctl: 1.8.4-beta (#4869)

tools/goctl/api/swagger/const.go

@@ -49,6 +49,7 @@ const (
 	propertyKeySchemes                 = "schemes"
 	propertyKeyTags                    = "tags"
 	propertyKeySummary                 = "summary"
+	propertyKeyOperationId             = "operationId"
 	propertyKeyDeprecated              = "deprecated"
 	propertyKeyPrefix                  = "prefix"
 	propertyKeyAuthType                = "authType"

tools/goctl/api/swagger/path.go

@@ -78,10 +78,11 @@ func spec2Path(ctx Context, group apiSpec.Group, route apiSpec.Route) spec.PathI
 			Schemes:     getListFromInfoOrDefault(route.AtDoc.Properties, propertyKeySchemes, []string{schemeHttps}),
 			Tags:        getListFromInfoOrDefault(group.Annotation.Properties, propertyKeyTags, getListFromInfoOrDefault(group.Annotation.Properties, propertyKeySummary, []string{})),
 			Summary:     getStringFromKVOrDefault(route.AtDoc.Properties, propertyKeySummary, getFirstUsableString(route.AtDoc.Text, route.Handler)),
+			ID:          getStringFromKVOrDefault(route.AtDoc.Properties, propertyKeyOperationId, getFirstUsableString(route.AtDoc.Text, route.Handler)),
 			Deprecated:  getBoolFromKVOrDefault(route.AtDoc.Properties, propertyKeyDeprecated, false),
+			Security:    security,
 			Parameters:  parametersFromType(ctx, route.Method, route.RequestType),
 			Responses:   jsonResponseFromType(ctx, route.AtDoc, route.ResponseType),
-			Security:    security,
 		},
 	}
 	externalDocsDescription := getStringFromKVOrDefault(route.AtDoc.Properties, propertyKeyExternalDocsDescription, "")

tools/goctl/build.env

@@ -1,2 +1,2 @@
 APP_NAME=goctl
-APP_VERSION=1.8.4-alpha
+APP_VERSION=1.8.4-beta

tools/goctl/change.md

@@ -0,0 +1,103 @@
+# 1.8.4-beta
+
+## swagger
+  - [features] Supported operation id for swagger
+## Other
+  - Updated version to 1.8.4-beta
+
+
+# 1.8.4-alpha
+
+## swagger
+1. [bug fix] remove example generation when request body are `query`, `path` and `header`
+- it not supported in api spec 2.0
+- it's will generate example when request body is json format.
+2. [features] swagger generation supported definitions
+- supported response definitions
+- supported json request body definitions
+- do not support query and form definitions, use parameters instead.
+
+**How to use?**
+Use the `useDefinitions` keyword in the info code block of the API file to declare the enable. This value is a boolean value. When set to `true`, it will enable the generation of definitions. Otherwise, it will be generated according to properties, and the default is `false`, for example:
+
+```go
+syntax = "v1"
+
+info (
+  ...
+  wrapCodeMsg: true
+  useDefinitions: true
+)
+...
+```
+
+the demo result of swagger.json
+
+```json
+{
+  ...
+  "responses": {
+          "200": {
+            "description": "",
+            "schema": {
+              "type": "object",
+              "properties": {
+                "code": {
+                  "description": "1001-User not login\u003cbr\u003e1002-User permission denied",
+                  "type": "integer",
+                  "example": 0
+                },
+                "data": {
+                  "$ref": "#/definitions/FormResp"
+                },
+                "msg": {
+                  "description": "business message",
+                  "type": "string",
+                  "example": "ok"
+                }
+              }
+            }
+          }
+        }
+  ...
+}
+```
+
+For a complete API example, please refer to the `api/swagger/example/example.api` file in pr. For a complete swagger result example, please refer to the `api/swagger/example/example.swagger.json` file in pr.
+
+## 2. `goctl api go` code generation
+- [bug-fix] Add flag `--type-group` to control the output of types(deprecated: experimental switch control type grouping is no longer used), if true, the types in only one group will separate by file.
+- example `goctl api go --api demo.api --dir demo --type-group`
+-  use `group` keyword in @server block to define  the group name in api file, for example
+```go
+@server(
+  group: user
+)
+service demo{
+  ...
+}
+```
+the example of separated types by file
+```
+.
+└── types
+    ├── common.go
+    ├── gotoolexport.go
+    ├── importfile.go
+    ├── process.go
+    └── types.go
+```
+
+## 3 API Parser
+- supported identifier value for info key-value in api parser
+  for example
+
+```
+syntax = "v1"
+
+info(
+  enable: true
+  disable: false
+)
+...
+```

tools/goctl/internal/version/version.go

@@ -6,7 +6,7 @@ import (
 )
 
 // BuildVersion is the version of goctl.
-const BuildVersion = "1.8.4-alpha"
+const BuildVersion = "1.8.4-beta"
 
 var tag = map[string]int{"pre-alpha": 0, "alpha": 1, "pre-bata": 2, "beta": 3, "released": 4, "": 5}