Code Generator (#610)

README.md

@@ -1,22 +1,27 @@
 # Qiniu Resource Storage SDK for Java
+
 [![@qiniu on weibo](http://img.shields.io/badge/weibo-%40qiniutek-blue.svg)](http://weibo.com/qiniutek)
 [![Software License](https://img.shields.io/badge/license-MIT-brightgreen.svg)](LICENSE)
 [![Build Status](https://travis-ci.org/qiniu/java-sdk.svg)](https://travis-ci.org/qiniu/java-sdk)
 [![GitHub release](https://img.shields.io/github/v/tag/qiniu/java-sdk.svg?label=release)](https://github.com/qiniu/java-sdk/releases)
 [![Docs](https://img.shields.io/github/v/tag/qiniu/java-sdk.svg?label=docs&color=yellow)](https://qiniu.github.io/java-sdk/)
 [![Coverage Status](https://codecov.io/gh/qiniu/java-sdk/branch/master/graph/badge.svg)](https://codecov.io/gh/qiniu/java-sdk)
 [![Latest Stable Version](https://img.shields.io/maven-central/v/com.qiniu/qiniu-java-sdk.svg)](http://search.maven.org/#search%7Cga%7C1%7Cg%3A%22com.qiniu%22%20AND%20a%3A%22qiniu-java-sdk%22)
+
 ## 安装
 
 下载 [the latest JAR][1] 或者 通过 Maven:
+
 ```xml
 <dependency>
   <groupId>com.qiniu</groupId>
   <artifactId>qiniu-java-sdk</artifactId>
   <version>[7.16.0, 7.16.99]</version>
 </dependency>
 ```
+
 或者 Gradle:
+
 ```groovy
 implementation 'com.qiniu:qiniu-java-sdk:7.16.+'
 ```
@@ -28,6 +33,7 @@ JDK 7 及以上
 ## 使用方法
 
 ### 上传
+
 ```Java
 // 分片上传 v1
 import com.qiniu.storage.UploadManager;
@@ -73,6 +79,7 @@ $ ./gradlew build
 ```
 
 ## 生成Eclipse工程文件
+
 ``` bash
 $ ./gradlew gen_eclipse
 ```
@@ -105,6 +112,9 @@ $ ./gradlew gen_eclipse
 The MIT License (MIT).详情见 [License文件](https://github.com/qiniu/java-sdk/blob/master/LICENSE).
 
 [1]: https://search.maven.org/remote_content?g=com.qiniu&a=qiniu-java-sdk&v=LATEST
+
 [2]: https://github.com/Nextpeer/okhttp
+
 [3]: https://raw.githubusercontent.com/qiniu/java-sdk/master/libs/okhttp-2.3.0-SNAPSHOT.jar
+
 [4]: https://raw.githubusercontent.com/qiniu/java-sdk/master/libs/okio-1.3.0-SNAPSHOT.jar

build.gradle

@@ -51,14 +51,14 @@ task getHomeDir {
 apply plugin: 'checkstyle'
 
 task apiJavadocs(type: Javadoc) {
-  source = sourceSets.main.allJava
-  classpath = sourceSets.main.runtimeClasspath
-  title = "七牛 Java SDK API 文档"
-  options {
-    memberLevel = JavadocMemberLevel.PUBLIC
-    setEncoding 'UTF-8'
-    setWindowTitle "七牛 Java SDK API 文档"
-  }
+    source = sourceSets.main.allJava
+    classpath = sourceSets.main.runtimeClasspath
+    title = "七牛 Java SDK API 文档"
+    options {
+        memberLevel = JavadocMemberLevel.PUBLIC
+        setEncoding 'UTF-8'
+        setWindowTitle "七牛 Java SDK API 文档"
+    }
 }
 
 def versionName() {

code-gen/go.mod

@@ -0,0 +1,19 @@
+module github.com/YangSen-qn/code-gen
+
+require (
+	github.com/getkin/kin-openapi v0.124.0
+	github.com/iancoleman/strcase v0.3.0
+	gopkg.in/yaml.v3 v3.0.1
+)
+
+require (
+	github.com/go-openapi/jsonpointer v0.20.2 // indirect
+	github.com/go-openapi/swag v0.22.8 // indirect
+	github.com/invopop/yaml v0.2.0 // indirect
+	github.com/josharian/intern v1.0.0 // indirect
+	github.com/mailru/easyjson v0.7.7 // indirect
+	github.com/mohae/deepcopy v0.0.0-20170929034955-c48cc78d4826 // indirect
+	github.com/perimeterx/marshmallow v1.1.5 // indirect
+)
+
+go 1.21.8

code-gen/src/api_desc.go

@@ -0,0 +1 @@
+package main

code-gen/src/apidesc/api.go

@@ -0,0 +1,16 @@
+package apidesc
+
+type ApiDetailedDescription struct {
+	Documentation string                 `yaml:"documentation,omitempty"`   // API 文档
+	PackageName   string                 `yaml:"package_name,omitempty"`    // 包名，文件路径中提取
+	Name          string                 `yaml:"name,omitempty"`            // API 名称，文件名
+	CamelCaseName string                 `yaml:"camel_case_name,omitempty"` // 驼峰命名
+	SnakeCaseName string                 `yaml:"snake_case_name,omitempty"` // 蛇形命名：特指下划线命名
+	Method        MethodName             `yaml:"method,omitempty"`          // HTTP 方法
+	ServiceNames  []ServiceName          `yaml:"service_names,omitempty"`   // 七牛服务名称
+	Command       string                 `yaml:"command,omitempty"`         // URL 查询命令
+	BasePath      string                 `yaml:"base_path,omitempty"`       // URL 基础路径
+	PathSuffix    string                 `yaml:"path_suffix,omitempty"`     // URL 路径后缀
+	Request       ApiRequestDescription  `yaml:"request,omitempty"`         // 请求参数
+	Response      ApiResponseDescription `yaml:"response,omitempty"`        // 响应参数
+}

code-gen/src/apidesc/body_json.go

@@ -0,0 +1,82 @@
+package apidesc
+
+import (
+	"fmt"
+
+	"gopkg.in/yaml.v3"
+)
+
+type (
+	JsonType struct {
+		String    bool        `yaml:"string,omitempty"`     // 字符串
+		Integer   bool        `yaml:"integer,omitempty"`    // 整型数字
+		Float     bool        `yaml:"float,omitempty"`      // 浮点型数字
+		Boolean   bool        `yaml:"boolean,omitempty"`    // 布尔值
+		Array     *JsonArray  `yaml:"array,omitempty"`      // 数组
+		Struct    *JsonStruct `yaml:"struct,omitempty"`     // 结构体
+		Any       bool        `yaml:"any,omitempty"`        // 任意数据结构
+		StringMap bool        `yaml:"string_map,omitempty"` // 任意字符串映射结构
+	}
+
+	JsonArray struct {
+		Documentation string    `yaml:"documentation,omitempty"`   // JSON 数组参数文档
+		Name          string    `yaml:"name,omitempty"`            // JSON 数组名称
+		CamelCaseName string    `yaml:"camel_case_name,omitempty"` // JSON 数组驼峰命名
+		SnakeCaseName string    `yaml:"snake_case_name,omitempty"` // JSON 数组下划线命名
+		Type          *JsonType `yaml:"type,omitempty"`            // JSON 数组类型
+	}
+
+	JsonStruct struct {
+		Documentation string      `yaml:"documentation,omitempty"`   // JSON 结构体参数文档
+		Name          string      `yaml:"name,omitempty"`            // JSON 结构体名称
+		CamelCaseName string      `yaml:"camel_case_name,omitempty"` // JSON 结构体驼峰命名
+		SnakeCaseName string      `yaml:"snake_case_name,omitempty"` // JSON 结构体下划线命名
+		Fields        []JsonField `yaml:"fields,omitempty"`          // JSON 字段列表
+	}
+
+	JsonField struct {
+		Documentation      string             `yaml:"documentation,omitempty"`         // JSON 字段参数文档
+		Key                string             `yaml:"key,omitempty"`                   // JSON 字段参数名称
+		FieldName          string             `yaml:"field_name,omitempty"`            // JSON 字段名称
+		FieldCamelCaseName string             `yaml:"field_camel_case_name,omitempty"` // JSON 字段驼峰命名
+		FieldSnakeCaseName string             `yaml:"field_snake_case_name,omitempty"` // JSON 字段下划线命名
+		Type               JsonType           `yaml:"type,omitempty"`                  // JSON 字段类型
+		Optional           *OptionalType      `yaml:"optional,omitempty"`              // JSON 字段是否可选，如果为空，则表示必填
+		ServiceBucket      *ServiceBucketType `yaml:"service_bucket,omitempty"`        // JSON 字段是否是空间名称，如果为空，则表示不是，如果不为空，则填写格式
+		ServiceObject      *ServiceObjectType `yaml:"service_object,omitempty"`        // JSON 字段是否是对象名称，如果为空，则表示不是，如果不为空，则填写格式
+	}
+)
+
+func (jsonType *JsonType) UnmarshalYAML(value *yaml.Node) error {
+	switch value.ShortTag() {
+	case "!!str":
+		switch value.Value {
+		case "string":
+			jsonType.String = true
+		case "integer":
+			jsonType.Integer = true
+		case "float":
+			jsonType.Float = true
+		case "boolean":
+			jsonType.Boolean = true
+		case "any":
+			jsonType.Any = true
+		case "string_map":
+			jsonType.StringMap = true
+		default:
+			return fmt.Errorf("unknown json type: %s", value.Value)
+		}
+		return nil
+	case "!!map":
+		switch value.Content[0].Value {
+		case "array":
+			return value.Content[1].Decode(&jsonType.Array)
+		case "struct":
+			return value.Content[1].Decode(&jsonType.Struct)
+		default:
+			return fmt.Errorf("unknown json type: %s", value.Content[0].Value)
+		}
+	default:
+		return fmt.Errorf("unknown json type: %s", value.ShortTag())
+	}
+}

code-gen/src/apidesc/consts.go

@@ -0,0 +1,95 @@
+package apidesc
+
+import (
+	"net/http"
+)
+
+type MethodName string
+
+const (
+	MethodNameGET    MethodName = http.MethodGet
+	MethodNamePOST   MethodName = http.MethodPost
+	MethodNamePUT    MethodName = http.MethodPut
+	MethodNameDELETE MethodName = http.MethodDelete
+)
+
+type ServiceName string
+
+const (
+	ServiceNameUp     ServiceName = "up"
+	ServiceNameIo     ServiceName = "io"
+	ServiceNameRs     ServiceName = "rs"
+	ServiceNameRsf    ServiceName = "rsf"
+	ServiceNameApi    ServiceName = "api"
+	ServiceNameBucket ServiceName = "uc"
+)
+
+// StringLikeType 类字符串参数类型
+type StringLikeType = string
+
+const (
+	StringLikeTypeString  StringLikeType = "string"  // 字符串
+	StringLikeTypeInteger StringLikeType = "integer" // 整型数字
+	StringLikeTypeFloat   StringLikeType = "float"   // 浮点型数字
+	StringLikeTypeBoolean StringLikeType = "boolean" // 布尔值
+)
+
+type MultipartFormDataType = string
+
+const (
+	MultipartFormDataTypeString      MultipartFormDataType = "string" // 字符串
+	MultipartFormDataTypeInteger     MultipartFormDataType = "integer"
+	MultipartFormDataTypeUploadToken MultipartFormDataType = "upload_token"
+	MultipartFormDataTypeBinaryData  MultipartFormDataType = "binary_data"
+)
+
+type OptionalType string
+
+const (
+	OptionalTypeRequired  OptionalType = ""          // 用户必须传值
+	OptionalTypeOmitEmpty OptionalType = "omitempty" // 如果用户不传值，则该字段省略
+	OptionalTypeKeepEmpty OptionalType = "keepempty" // 即使用户不传值，也会发送空值
+	OptionalTypeNullable  OptionalType = "nullable"  // 如果用户不传值，则该字段省略，但如果用户传值，即使是空值也会发送
+)
+
+type Authorization string
+
+const (
+	AuthorizationNone    Authorization = ""
+	AuthorizationQbox    Authorization = "Qbox"
+	AuthorizationQiniu   Authorization = "qiniu"
+	AuthorizationUpToken Authorization = "UploadToken"
+)
+
+type Idempotent string
+
+const (
+	IdempotentDefault Idempotent = "default" // 默认幂等性（根据 HTTP 方法判定）
+	IdempotentAlways  Idempotent = "always"  // 总是幂等
+	IdempotentNever   Idempotent = "never"   // 总是不幂等
+)
+
+type EncodeType string
+
+const (
+	EncodeTypeNone                EncodeType = "none"
+	EncodeTypeUrlSafeBase64       EncodeType = "url_safe_base64"         // 需要进行编码
+	EncodeTypeUrlSafeBase64OrNone EncodeType = "url_safe_base64_or_none" // 不仅需要编码，即使路径参数的值是 None 也要编码。该选项暗示了 nullable
+)
+
+type ServiceBucketType string
+
+const (
+	ServiceBucketTypeNone        ServiceBucketType = ""             //
+	ServiceBucketTypePlainText   ServiceBucketType = "plain_text"   // 该值为存储空间名称
+	ServiceBucketTypeEntry       ServiceBucketType = "entry"        // 该值格式为 UrlSafeBase64("$bucket:$key")
+	ServiceBucketTypeUploadToken ServiceBucketType = "upload_token" // 该值为上传凭证，内部包含存储空间信息
+)
+
+type ServiceObjectType string
+
+const (
+	ServiceObjectTypeNone      ServiceObjectType = ""           //
+	ServiceObjectTypePlainText ServiceObjectType = "plain_text" // 该值为对象名称
+	ServiceObjectTypeEntry     ServiceObjectType = "entry"      // 该值格式为 UrlSafeBase64("$bucket:$key")
+)

code-gen/src/apidesc/header.go

@@ -0,0 +1,12 @@
+package apidesc
+
+type HeaderName struct {
+	HeaderName         string        `yaml:"header_name,omitempty"`           // HTTP 头名称
+	Documentation      string        `yaml:"documentation,omitempty"`         // HTTP 头参数文档
+	FieldName          string        `yaml:"field_name,omitempty"`            // HTTP 头参数名称
+	FieldCamelCaseName string        `yaml:"field_camel_case_name,omitempty"` // HTTP 头参数驼峰命名
+	FieldSnakeCaseName string        `yaml:"field_snake_case_name,omitempty"` // HTTP 头参数下划线命名
+	Optional           *OptionalType `yaml:"optional,omitempty"`              // HTTP 头参数是否可选，如果为空，则表示必填
+}
+
+type HeaderNames []HeaderName

code-gen/src/apidesc/request.go

@@ -0,0 +1,77 @@
+package apidesc
+
+import (
+	"fmt"
+
+	"gopkg.in/yaml.v3"
+)
+
+type NamedPathParam struct {
+	Documentation      string             `yaml:"documentation,omitempty"`         // URL 路径参数文档
+	PathSegment        string             `yaml:"path_segment,omitempty"`          // URL 路径段落，如果为空，则表示参数直接追加在 URL 路径末尾
+	FieldName          string             `yaml:"field_name,omitempty"`            // URL 路径参数名称
+	FieldCamelCaseName string             `yaml:"field_camel_case_name,omitempty"` // URL 路径参数驼峰命名
+	FieldSnakeCaseName string             `yaml:"field_snake_case_name,omitempty"` // URL 路径参数下划线命名
+	Type               *StringLikeType    `yaml:"type,omitempty"`                  // URL 路径参数类型
+	Encode             *EncodeType        `yaml:"encode,omitempty"`                // URL 路径参数编码方式，如果为空，表示直接转码成字符串
+	ServiceBucket      *ServiceBucketType `yaml:"service_bucket,omitempty"`        // URL 路径参数是否是空间名称，如果为空，则表示不是，如果不为空，则填写格式
+	ServiceObject      *ServiceObjectType `yaml:"service_object,omitempty"`        // URL 路径参数是否是对象名称，如果为空，则表示不是，如果不为空，则填写格式
+	Optional           *OptionalType      `yaml:"optional,omitempty"`              // URL 路径参数是否可选，如果为空，则表示必填
+}
+
+type FreePathParams struct {
+	FieldName          string      `yaml:"field_name,omitempty"`            // URL 路径参数名称
+	FieldCamelCaseName string      `yaml:"field_camel_case_name,omitempty"` // URL 路径参数驼峰命名
+	FieldSnakeCaseName string      `yaml:"field_snake_case_name,omitempty"` // URL 路径参数下划线命名
+	Documentation      string      `yaml:"documentation,omitempty"`         // URL 路径参数文档
+	EncodeParamKey     *EncodeType `yaml:"encode_param_key"`                // URL 路径参数键编码方式，如果为空，表示直接转码成字符串
+	EncodeParamValue   *EncodeType `yaml:"encode_param_value"`              // URL 路径参数值编码方式，如果为空，表示直接转码成字符串
+}
+
+type PathParams struct {
+	Named []NamedPathParam `yaml:"named,omitempty"` // URL 路径有名参数列表
+	Free  *FreePathParams  `yaml:"free,omitempty"`  // URL 路径自由参数列表
+}
+
+type RequestBody struct {
+	Json              *JsonType                    `yaml:"json,omitempty"`                // JSON 类型
+	FormUrlencoded    *FormUrlencodedRequestStruct `yaml:"form_urlencoded,omitempty"`     // URL 编码表单调用（无法上传二进制数据）
+	MultipartFormData *MultipartFormFields         `yaml:"multipart_form_data,omitempty"` // 复合表单调用（可以上传二进制数据）
+	BinaryData        bool                         `yaml:"binary_data,omitempty"`         // 二进制数据
+}
+
+func (body *RequestBody) UnmarshalYAML(value *yaml.Node) error {
+	switch value.ShortTag() {
+	case "!!str":
+		switch value.Value {
+		case "binary_data":
+			body.BinaryData = true
+		default:
+			return fmt.Errorf("unknown request body type: %s", value.Value)
+		}
+		return nil
+	case "!!map":
+		switch value.Content[0].Value {
+		case "json":
+			return value.Content[1].Decode(&body.Json)
+		case "form_urlencoded":
+			return value.Content[1].Decode(&body.FormUrlencoded)
+		case "multipart_form_data":
+			return value.Content[1].Decode(&body.MultipartFormData)
+		default:
+			return fmt.Errorf("unknown request body type: %s", value.Content[0].Value)
+		}
+	default:
+		return fmt.Errorf("unknown request body type: %s", value.ShortTag())
+	}
+}
+
+type ApiRequestDescription struct {
+	PathParams           *PathParams    `yaml:"path_params,omitempty"`   // URL 路径参数列表
+	HeaderNames          HeaderNames    `yaml:"header_names,omitempty"`  // HTTP 头参数列表
+	QueryNames           QueryNames     `yaml:"query_names,omitempty"`   // URL 查询参数列表
+	Body                 *RequestBody   `yaml:"body,omitempty"`          // 请求体
+	Authorization        *Authorization `yaml:"authorization,omitempty"` // 鉴权参数
+	Idempotent           *Idempotent    `yaml:"idempotent,omitempty"`    // 幂等性
+	responseTypeRequired bool           `yaml:"response_type_required"`  //
+}