From 45b27ad93ac043dba90a9a5a16385ccc7d49bc0b Mon Sep 17 00:00:00 2001 From: kesonan Date: Mon, 19 May 2025 23:30:50 +0800 Subject: [PATCH] goctl: 1.8.4-beta (#4869) --- tools/goctl/api/swagger/const.go | 1 + tools/goctl/api/swagger/path.go | 3 +- tools/goctl/build.env | 2 +- tools/goctl/change.md | 103 ++++++++++++++++++++++++ tools/goctl/internal/version/version.go | 2 +- 5 files changed, 108 insertions(+), 3 deletions(-) create mode 100644 tools/goctl/change.md diff --git a/tools/goctl/api/swagger/const.go b/tools/goctl/api/swagger/const.go index 87ea53bfb..e965d52b4 100644 --- a/tools/goctl/api/swagger/const.go +++ b/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" diff --git a/tools/goctl/api/swagger/path.go b/tools/goctl/api/swagger/path.go index e3379ca3c..545b25541 100644 --- a/tools/goctl/api/swagger/path.go +++ b/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, "") diff --git a/tools/goctl/build.env b/tools/goctl/build.env index 1adc005bb..2eea60f56 100644 --- a/tools/goctl/build.env +++ b/tools/goctl/build.env @@ -1,2 +1,2 @@ APP_NAME=goctl -APP_VERSION=1.8.4-alpha \ No newline at end of file +APP_VERSION=1.8.4-beta \ No newline at end of file diff --git a/tools/goctl/change.md b/tools/goctl/change.md new file mode 100644 index 000000000..a9de4e4f9 --- /dev/null +++ b/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 +) +... +``` \ No newline at end of file diff --git a/tools/goctl/internal/version/version.go b/tools/goctl/internal/version/version.go index ed5de9b5e..9dd7dd872 100644 --- a/tools/goctl/internal/version/version.go +++ b/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}