goctl: support custom swagger authentication (#4811)

tools/goctl/api/swagger/const.go

@@ -29,8 +29,4 @@ const (
 	schemeHttps     = "https"
 	defaultHost     = "127.0.0.1"
 	defaultBasePath = "/"
-
-	swaggerSecurityDefinitionBearerAuth = "BearerAuth"
-	swaggerSecurityDefinitionName       = "Authorization"
-	swaggerSecurityDefinitionIn         = "header"
 )

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

@@ -17,6 +17,10 @@ info (
 	basePath:               "/v1" // basePath corresponding to Swagger,default value is `/`
 	wrapCodeMsg:            "true" // to wrap in the universal code-msg structure, like {"code":0,"msg":"OK","data":$data}
 	bizCodeEnumDescription: "1001-User not login<br>1002-User permission denied" // enums of business error codes, in JSON format, with the key being the business error code and the value being the description of that error code. This only takes effect when wrapCodeMsg is set to true.
+	// securityDefinitionsFromJson is a custom authentication configuration, and the JSON content will be directly inserted into the securityDefinitions of Swagger.
+	// Format reference: https://swagger.io/specification/v2/#security-definitions-object
+	// You can declare authType in the @server of the API to specify the authentication type used for its routes.
+	securityDefinitionsFromJson: `{"apiKey":{"description":"apiKey type description","type":"apiKey","name":"x-api-key","in":"header"}}`
 )
 
 type (
@@ -42,6 +46,8 @@ type (
 @server (
 	tags:    "query" // tags corresponding to Swagger
 	summary: "query API set" // summary corresponding to Swagger
+	prefix: v1
+	authType: apiKey // Specifies the authentication type used for this route, which is the name defined in securityDefinitionsFromJson.
 )
 service Swagger {
 	@doc (

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

@@ -17,6 +17,10 @@ info (
 	basePath:               "/v1" // 对应 swagger 的 basePath,不填默认为 /
 	wrapCodeMsg:            "true" // 是否用 code-msg 通用响应体，如果开启，则以格式 {"code":0,"msg":"OK","data":$data} 包括响应体
 	bizCodeEnumDescription: "1001-未登录<br>1002-无权限操作" // 业务错误码枚举描述，json 格式,key 为业务错误码，value 为该错误码的描述，仅当 wrapCodeMsg 为 true 时生效
+	// securityDefinitionsFromJson 为自定义鉴权配置，json 内容将直接放入 swagger 的 securityDefinitions 中，
+	// 格式参考 https://swagger.io/specification/v2/#security-definitions-object
+	// 在 api 的 @server 中可声明 authType 来指定其路由使用的鉴权类型
+	securityDefinitionsFromJson: `{"apiKey":{"description":"apiKey 类型鉴权自定义","type":"apiKey","name":"x-api-key","in":"header"}}`
 )
 
 type (
@@ -43,7 +47,7 @@ type (
 	tags:    "query 演示" // 对应 swagger 的 tags,可以对 swagger 中的 api 进行分组
 	summary: "query 类型接口集合" // 对应 swagger 的 summary
 	prefix: v1
-	jwt: Auth
+	authType: apiKey // 指定该路由使用的鉴权类型，值为 securityDefinitionsFromJson 中定义的名称
 )
 service Swagger {
 	@doc (

tools/goctl/api/swagger/path.go

@@ -61,12 +61,12 @@ func mergePathItem(old, new spec.PathItem) spec.PathItem {
 }
 
 func spec2Path(info apiSpec.Info, group apiSpec.Group, route apiSpec.Route) spec.PathItem {
-	needJwt := hasKey(group.Annotation.Properties, "jwt")
+	authType := getStringFromKVOrDefault(group.Annotation.Properties, "authType", "")
 	var security []map[string][]string
-	if needJwt {
+	if len(authType) > 0 {
 		security = []map[string][]string{
 			{
-				swaggerSecurityDefinitionBearerAuth: []string{},
+				authType: []string{},
 			},
 		}
 	}

tools/goctl/api/swagger/swagger.go

@@ -1,6 +1,7 @@
 package swagger
 
 import (
+	"encoding/json"
 	"strings"
 	"time"
 
@@ -13,22 +14,23 @@ import (
 func spec2Swagger(api *apiSpec.ApiSpec) (*spec.Swagger, error) {
 	extensions, info := specExtensions(api.Info)
 
+	var securityDefinitions spec.SecurityDefinitions
+	securityDefinitionsFromJson := getStringFromKVOrDefault(api.Info.Properties, "securityDefinitionsFromJson", `{}`)
+	_ = json.Unmarshal([]byte(securityDefinitionsFromJson), &securityDefinitions)
 	swagger := &spec.Swagger{
 		VendorExtensible: spec.VendorExtensible{
 			Extensions: extensions,
 		},
 		SwaggerProps: spec.SwaggerProps{
-			Consumes: getListFromInfoOrDefault(api.Info.Properties, "consumes", []string{applicationJson}),
-			Produces: getListFromInfoOrDefault(api.Info.Properties, "produces", []string{applicationJson}),
-			Schemes:  getListFromInfoOrDefault(api.Info.Properties, "schemes", []string{schemeHttps}),
-			Swagger:  swaggerVersion,
-			Info:     info,
-			Host:     getStringFromKVOrDefault(api.Info.Properties, "host", defaultHost),
-			BasePath: getStringFromKVOrDefault(api.Info.Properties, "basePath", defaultBasePath),
-			Paths:    spec2Paths(api.Info, api.Service),
-			SecurityDefinitions: spec.SecurityDefinitions{
-				swaggerSecurityDefinitionBearerAuth: spec.APIKeyAuth(swaggerSecurityDefinitionName, swaggerSecurityDefinitionIn),
-			},
+			Consumes:            getListFromInfoOrDefault(api.Info.Properties, "consumes", []string{applicationJson}),
+			Produces:            getListFromInfoOrDefault(api.Info.Properties, "produces", []string{applicationJson}),
+			Schemes:             getListFromInfoOrDefault(api.Info.Properties, "schemes", []string{schemeHttps}),
+			Swagger:             swaggerVersion,
+			Info:                info,
+			Host:                getStringFromKVOrDefault(api.Info.Properties, "host", defaultHost),
+			BasePath:            getStringFromKVOrDefault(api.Info.Properties, "basePath", defaultBasePath),
+			Paths:               spec2Paths(api.Info, api.Service),
+			SecurityDefinitions: securityDefinitions,
 		},
 	}