chore: update some docs

hertz-contrib · Aug 7, 2024 · bf1f61c · bf1f61c
1 parent f62e636
commit bf1f61c
Show file tree

Hide file tree

Showing 8 changed files with 89 additions and 35 deletions.
diff --git a/thrift-gen-http-swagger/README.md b/thrift-gen-http-swagger/README.md
@@ -64,13 +64,13 @@ HTTP Swagger document generation plugin for cloudwego/cwgo & hertz.
 
 ## openapi Annotations
 
-| Annotation          | Component | Explanation                                                     |  
-|---------------------|-----------|-----------------------------------------------------------------|
-| `openapi.operation` | Method    | Used to supplement the `operation` of `pathItem`                |
-| `openapi.property`  | Field     | Used to supplement the `property` of `schema`                   |
-| `openapi.schema`    | Message   | Used to supplement the `schema` of `requestBody` and `response` |
-| `openapi.document`  | Document  | Used to supplement the Swagger document                         |
-| `openapi.parameter` | Field     | Used to supplement the `parameter`                              |
+| Annotation          | Component | Explanation                                                                        |  
+|---------------------|-----------|------------------------------------------------------------------------------------|
+| `openapi.operation` | Method    | Used to supplement the `operation` of `pathItem`                                   |
+| `openapi.property`  | Field     | Used to supplement the `property` of `schema`                                      |
+| `openapi.schema`    | Struct    | Used to supplement the `schema` of `requestBody` and `response`                    |
+| `openapi.document`  | Service   | Used to supplement the Swagger document, simply add this annotation in any service |
+| `openapi.parameter` | Field     | Used to supplement the `parameter`                                                 |
 
 For more usage, please refer to [Example](example/hello.thrift).
 
@@ -90,6 +90,14 @@ go install github.com/hertz-contrib/swagger-generate/thrift-gen-http-swagger@lat
 thrift-gen-http-swagger --version
 ```
 
+## Usage
+
+```sh
+
+thriftgo -g go -p http-swagger:OutputDir={swagger documentation output directory} {idl}.thrift
+
+```
+
 ## More info
 
 See [examples](example/hello.thrift)
diff --git a/thrift-gen-http-swagger/README_CN.md b/thrift-gen-http-swagger/README_CN.md
@@ -68,8 +68,8 @@
 |---------------------|---------|--------------------------------------------|
 | `openapi.operation` | Method  | 用于补充 `pathItem` 的 `operation`              |
 | `openapi.property`  | Field   | 用于补充 `schema` 的 `property`                 |
-| `openapi.schema`    | Message | 用于补充 `requestBody` 和 `response` 的 `schema` |
-| `openapi.document`  | 文档      | 用于补充 swagger 文档                            |
+| `openapi.schema`    | Struct  | 用于补充 `requestBody` 和 `response` 的 `schema` |
+| `openapi.document`  | Service | 用于补充 swagger 文档，任意service中添加该注解即可          |
 | `openapi.parameter` | Field   | 用于补充 `parameter`                           |
 
 更多的使用方法请参考 [示例](example/hello.thrift)
@@ -91,6 +91,14 @@ go install github.com/hertz-contrib/swagger-generate/thrift-gen-http-swagger@lat
 thrift-gen-http-swagger --version
 ```
 
+## 使用
+
+```sh
+
+thriftgo -g go -p http-swagger:OutputDir={swagger文档输出目录} {idl}.thrift
+
+```
+
 ## 更多信息
 
 查看 [示例](example/hello.thrift)

diff --git a/thrift-gen-http-swagger/example/docs/openapi.yaml b/thrift-gen-http-swagger/example/docs/openapi.yaml
@@ -3,9 +3,8 @@
 
 openapi: 3.0.3
 info:
-    title: API generated by thrift-gen-http-swagger
-    description: API description
-    version: 1.0.0
+    title: example swagger doc
+    version: Version from annotation
 servers:
     - url: http://127.0.0.1:8888
     - url: http://127.0.0.1:8889
@@ -105,6 +104,11 @@ paths:
                         type: string
                 - name: query1
                   in: query
+                  description: |-
+                    对于map类型调试时需要转义才能解析，如下所示
+                     {
+                       "query1":  "{\"key\":\"value\"}"
+                     }
                   schema:
                     type: object
                     additionalProperties:
@@ -147,6 +151,11 @@ paths:
                         type: string
                 - name: query1
                   in: query
+                  description: |-
+                    对于map类型调试时需要转义才能解析，如下所示
+                     {
+                       "query1":  "{\"key\":\"value\"}"
+                     }
                   schema:
                     type: object
                     additionalProperties:

diff --git a/thrift-gen-http-swagger/example/hello.thrift b/thrift-gen-http-swagger/example/hello.thrift
@@ -46,10 +46,17 @@ struct QueryReq {
             max_length: 50
         }'
     )
-    6: list<string> items (
+    2: list<string> items (
         api.query = "items"
     )
-    7: map<string, string> strings_map (
+
+    /*
+    * 对于paramters中的map类型调试时需要转义才能解析，如下所示
+    * {
+    *   "query1":  "{\"key\":\"value\"}"
+    * }
+    */
+    3: map<string, string> strings_map (
         api.query = "query1"
     )
 }

diff --git a/thrift-gen-http-swagger/generator/generator.go b/thrift-gen-http-swagger/generator/generator.go
@@ -694,20 +694,37 @@ func (g *OpenAPIGenerator) filterCommentString(str string) string {
 	matches := g.commentPattern.FindAllStringSubmatch(str, -1)
 
 	for _, match := range matches {
-		var comment string
 		if match[1] != "" {
-			// One-line comment
-			comment = strings.TrimSpace(match[1])
+			// Handle one-line comments
+			comments = append(comments, strings.TrimSpace(match[1]))
 		} else if match[2] != "" {
-			// Multiline comment
+			// Handle multiline comments
 			multiLineComment := match[2]
 			lines := strings.Split(multiLineComment, "\n")
+
+			// Find the minimum indentation level (excluding empty lines)
+			minIndent := -1
+			for _, line := range lines {
+				trimmedLine := strings.TrimSpace(line)
+				if trimmedLine != "" {
+					lineIndent := len(line) - len(strings.TrimLeft(line, " "))
+					if minIndent == -1 || lineIndent < minIndent {
+						minIndent = lineIndent
+					}
+				}
+			}
+
+			// Remove the minimum indentation and any leading '*' from each line
 			for i, line := range lines {
-				lines[i] = strings.TrimSpace(strings.TrimPrefix(strings.TrimSpace(line), "*"))
+				if minIndent > 0 && len(line) >= minIndent {
+					line = line[minIndent:]
+				}
+				lines[i] = strings.TrimPrefix(line, "*")
 			}
-			comment = strings.Join(lines, "\n")
+
+			// Remove leading and trailing empty lines from the comment block
+			comments = append(comments, strings.TrimSpace(strings.Join(lines, "\n")))
 		}
-		comments = append(comments, comment)
 	}
 
 	return strings.Join(comments, "\n")

diff --git a/thrift-gen-http-swagger/go.mod b/thrift-gen-http-swagger/go.mod
@@ -1,6 +1,6 @@
 module github.com/hertz-contrib/swagger-generate/thrift-gen-http-swagger
 
-go 1.22
+go 1.16
 
 require (
 	github.com/apache/thrift v0.13.0
@@ -9,8 +9,3 @@ require (
 	github.com/google/gnostic-models v0.6.8
 	gopkg.in/yaml.v3 v3.0.1
 )
-
-require (
-	github.com/golang/protobuf v1.5.2 // indirect
-	google.golang.org/protobuf v1.28.0 // indirect
-)
diff --git a/thrift-gen-http-swagger/go.sum b/thrift-gen-http-swagger/go.sum
@@ -154,6 +154,7 @@ google.golang.org/protobuf v1.23.1-0.20200526195155-81db48ad09cc/go.mod h1:EGpAD
 google.golang.org/protobuf v1.25.0/go.mod h1:9JNX74DMeImyA3h4bdi1ymwjUzf21/xIlbajtzgsN7c=
 google.golang.org/protobuf v1.26.0-rc.1/go.mod h1:jlhhOSvTdKEhbULTjvd4ARK9grFBp09yW+WbY/TyQbw=
 google.golang.org/protobuf v1.26.0/go.mod h1:9q0QmTI4eRPtz6boOQmLYwt+qCgq0jsYwAQnmE0givc=
+google.golang.org/protobuf v1.27.1/go.mod h1:9q0QmTI4eRPtz6boOQmLYwt+qCgq0jsYwAQnmE0givc=
 google.golang.org/protobuf v1.28.0 h1:w43yiav+6bVFTBQFZX0r7ipe9JQ1QsbMgHwbBziscLw=
 google.golang.org/protobuf v1.28.0/go.mod h1:HV8QOd/L58Z+nl8r43ehVNZIU/HEI6OcFqwMG9pJV4I=
 gopkg.in/check.v1 v0.0.0-20161208181325-20d25e280405/go.mod h1:Co6ibVJAznAaIkqp8huTwlJQCZ016jof/cbN4VW5Yz0=
@@ -164,6 +165,7 @@ gopkg.in/yaml.v2 v2.2.2/go.mod h1:hI93XBmqTisBFMUTm0b8Fm+jr3Dg1NNxqwp+5A1VGuI=
 gopkg.in/yaml.v2 v2.2.8/go.mod h1:hI93XBmqTisBFMUTm0b8Fm+jr3Dg1NNxqwp+5A1VGuI=
 gopkg.in/yaml.v2 v2.3.0/go.mod h1:hI93XBmqTisBFMUTm0b8Fm+jr3Dg1NNxqwp+5A1VGuI=
 gopkg.in/yaml.v2 v2.4.0/go.mod h1:RDklbk79AGWmwhnvt/jBztapEOGDOx6ZbXqjP6csGnQ=
+gopkg.in/yaml.v3 v3.0.0-20210107192922-496545a6307b/go.mod h1:K4uyk7z7BCEPqu6E+C64Yfv1cQ7kz7rIZviUmN+EgEM=
 gopkg.in/yaml.v3 v3.0.1 h1:fxVm/GzAzEWqLHuvctI91KS9hhNmmWOoWu0XTYJS7CA=
 gopkg.in/yaml.v3 v3.0.1/go.mod h1:K4uyk7z7BCEPqu6E+C64Yfv1cQ7kz7rIZviUmN+EgEM=
 honnef.co/go/tools v0.0.0-20190102054323-c2f93a96b099/go.mod h1:rf3lG4BRIbNafJWhAfAdb/ePZxsR/4RtNHQocxwk9r4=

diff --git a/thrift-gen-http-swagger/utils/utils.go b/thrift-gen-http-swagger/utils/utils.go
@@ -41,6 +41,9 @@ func Contains(s []string, e string) bool {
 
 func ParseStructOption(descriptor *thrift_reflection.StructDescriptor, optionName string, obj interface{}) error {
 	opt, err := thrift_option.ParseStructOption(descriptor, optionName)
+	if errors.Is(err, thrift_option.ErrKeyNotMatch) {
+		return nil
+	}
 	if err != nil {
 		return err
 	}
@@ -50,15 +53,17 @@ func ParseStructOption(descriptor *thrift_reflection.StructDescriptor, optionNam
 	if err != nil {
 		return err
 	}
-	err = json.Unmarshal(jsonData, obj)
-	if err != nil {
+	if err = json.Unmarshal(jsonData, obj); err != nil {
 		return err
 	}
 	return err
 }
 
 func ParseServiceOption(descriptor *thrift_reflection.ServiceDescriptor, optionName string, obj interface{}) error {
 	opt, err := thrift_option.ParseServiceOption(descriptor, optionName)
+	if errors.Is(err, thrift_option.ErrKeyNotMatch) {
+		return nil
+	}
 	if err != nil {
 		return err
 	}
@@ -68,15 +73,17 @@ func ParseServiceOption(descriptor *thrift_reflection.ServiceDescriptor, optionN
 	if err != nil {
 		return err
 	}
-	err = json.Unmarshal(jsonData, obj)
-	if err != nil {
+	if err = json.Unmarshal(jsonData, obj); err != nil {
 		return err
 	}
 	return err
 }
 
 func ParseMethodOption(descriptor *thrift_reflection.MethodDescriptor, optionName string, obj interface{}) error {
 	opt, err := thrift_option.ParseMethodOption(descriptor, optionName)
+	if errors.Is(err, thrift_option.ErrKeyNotMatch) {
+		return nil
+	}
 	if err != nil {
 		return err
 	}
@@ -86,15 +93,17 @@ func ParseMethodOption(descriptor *thrift_reflection.MethodDescriptor, optionNam
 	if err != nil {
 		return err
 	}
-	err = json.Unmarshal(jsonData, obj)
-	if err != nil {
+	if err = json.Unmarshal(jsonData, obj); err != nil {
 		return err
 	}
 	return err
 }
 
 func ParseFieldOption(descriptor *thrift_reflection.FieldDescriptor, optionName string, obj interface{}) error {
 	opt, err := thrift_option.ParseFieldOption(descriptor, optionName)
+	if errors.Is(err, thrift_option.ErrKeyNotMatch) {
+		return nil
+	}
 	if err != nil {
 		return err
 	}
@@ -104,8 +113,7 @@ func ParseFieldOption(descriptor *thrift_reflection.FieldDescriptor, optionName
 	if err != nil {
 		return err
 	}
-	err = json.Unmarshal(jsonData, obj)
-	if err != nil {
+	if err = json.Unmarshal(jsonData, obj); err != nil {
 		return err
 	}
 	return err