release goctl swagger (#4829)

tools/goctl/api/cmd.go

@@ -16,7 +16,6 @@ import (
 	"github.com/zeromicro/go-zero/tools/goctl/api/validate"
 	"github.com/zeromicro/go-zero/tools/goctl/config"
 	"github.com/zeromicro/go-zero/tools/goctl/internal/cobrax"
-	"github.com/zeromicro/go-zero/tools/goctl/pkg/env"
 	"github.com/zeromicro/go-zero/tools/goctl/plugin"
 )
 
@@ -110,8 +109,5 @@ func init() {
 	validateCmdFlags.StringVar(&validate.VarStringAPI, "api")
 
 	// Add sub-commands
-	Cmd.AddCommand(dartCmd, docCmd, formatCmd, goCmd, javaCmd, ktCmd, newCmd, pluginCmd, tsCmd, validateCmd)
+	Cmd.AddCommand(dartCmd, docCmd, formatCmd, goCmd, javaCmd, ktCmd, newCmd, pluginCmd, tsCmd, validateCmd, swaggerCmd)
-	if env.UseExperimental() {
-		Cmd.AddCommand(swaggerCmd)
-	}
 }

tools/goctl/api/swagger/example/example_cn.api

@@ -16,7 +16,7 @@ info (
 	host:                   "example.com" // 对应 swagger 的 host,不填默认为 127.0.0.1
 	basePath:               "/v1" // 对应 swagger 的 basePath,不填默认为 /
 	wrapCodeMsg:            "true" // 是否用 code-msg 通用响应体，如果开启，则以格式 {"code":0,"msg":"OK","data":$data} 包括响应体
-	bizCodeEnumDescription: "1001-未登录<br>1002-无权限操作" // 业务错误码枚举描述，json 格式,key 为业务错误码，value 为该错误码的描述，仅当 wrapCodeMsg 为 true 时生效
+	bizCodeEnumDescription: "1001-未登录<br>1002-无权限操作" // 全局业务错误码枚举描述，json 格式,key 为业务错误码，value 为该错误码的描述，仅当 wrapCodeMsg 为 true 时生效
 	// securityDefinitionsFromJson 为自定义鉴权配置，json 内容将直接放入 swagger 的 securityDefinitions 中，
 	// 格式参考 https://swagger.io/specification/v2/#security-definitions-object
 	// 在 api 的 @server 中可声明 authType 来指定其路由使用的鉴权类型
@@ -52,6 +52,7 @@ type (
 service Swagger {
 	@doc (
 		description: "query 接口"
+		bizCodeEnumDescription: " 1003-用不存在<br>1004-非法操作" // 接口级别业务错误码枚举描述，会覆盖全局的业务错误码，json 格式,key 为业务错误码，value 为该错误码的描述，仅当 wrapCodeMsg 为 true 时生效
 	)
 	@handler query
 	get /query (QueryReq) returns (QueryResp)

tools/goctl/api/swagger/path.go

@@ -80,7 +80,7 @@ func spec2Path(info apiSpec.Info, group apiSpec.Group, route apiSpec.Route) spec
 			Summary:     getStringFromKVOrDefault(route.AtDoc.Properties, "summary", getFirstUsableString(route.AtDoc.Text, route.Handler)),
 			Deprecated:  getBoolFromKVOrDefault(route.AtDoc.Properties, "deprecated", false),
 			Parameters:  parametersFromType(route.Method, route.RequestType),
-			Responses:   jsonResponseFromType(info, route.ResponseType),
+			Responses:   jsonResponseFromType(info, route.AtDoc, route.ResponseType),
 			Security:    security,
 		},
 	}

tools/goctl/api/swagger/response.go

@@ -5,7 +5,7 @@ import (
 	apiSpec "github.com/zeromicro/go-zero/tools/goctl/api/spec"
 )
 
-func jsonResponseFromType(info apiSpec.Info, tp apiSpec.Type) *spec.Responses {
+func jsonResponseFromType(info apiSpec.Info, atDoc apiSpec.AtDoc, tp apiSpec.Type) *spec.Responses {
 	p, _ := propertiesFromType(tp)
 	props := spec.SchemaProps{
 		Type:                 typeFromGoType(tp),
@@ -19,7 +19,7 @@ func jsonResponseFromType(info apiSpec.Info, tp apiSpec.Type) *spec.Responses {
 			Default: &spec.Response{
 				ResponseProps: spec.ResponseProps{
 					Schema: &spec.Schema{
-						SchemaProps: wrapCodeMsgProps(props, info),
+						SchemaProps: wrapCodeMsgProps(props, info, atDoc),
 					},
 				},
 			},

tools/goctl/api/swagger/swagger.go

@@ -256,11 +256,13 @@ func pathVariable2SwaggerVariable(path string) string {
 	return "/" + strings.Join(resp, "/")
 }
 
-func wrapCodeMsgProps(properties spec.SchemaProps, api apiSpec.Info) spec.SchemaProps {
+func wrapCodeMsgProps(properties spec.SchemaProps, api apiSpec.Info, atDoc apiSpec.AtDoc) spec.SchemaProps {
 	wrapCodeMsg := getBoolFromKVOrDefault(api.Properties, "wrapCodeMsg", false)
 	if !wrapCodeMsg {
 		return properties
 	}
+	globalCodeDesc := getStringFromKVOrDefault(api.Properties, "bizCodeEnumDescription", "business code")
+	methodCodeDesc := getStringFromKVOrDefault(atDoc.Properties, "bizCodeEnumDescription", globalCodeDesc)
 	return spec.SchemaProps{
 		Type: []string{swaggerTypeObject},
 		Properties: spec.SchemaProperties{
@@ -270,7 +272,7 @@ func wrapCodeMsgProps(properties spec.SchemaProps, api apiSpec.Info) spec.Schema
 				},
 				SchemaProps: spec.SchemaProps{
 					Type:        []string{swaggerTypeInteger},
-					Description: getStringFromKVOrDefault(api.Properties, "bizCodeEnumDescription", "business code"),
+					Description: methodCodeDesc,
 				},
 			},
 			"msg": {