fix: content type

hertz-contrib · Aug 10, 2024 · 5c46d33 · 5c46d33
1 parent b7aa07e
commit 5c46d33
Show file tree

Hide file tree

Showing 5 changed files with 96 additions and 59 deletions.
diff --git a/protoc-gen-http-swagger/README.md b/protoc-gen-http-swagger/README.md
@@ -2,7 +2,7 @@
 
 English | [中文](README_CN.md)
 
-HTTP Swagger document generation plugin for cloudwego/cwgo & hertz.
+HTTP Swagger document generation plugin for [cloudwego/cwgo](https://github.com/cloudwego/cwgo) & [hertz](https://github.com/cloudwego/hertz).
 
 ## Supported hz Annotations
 
@@ -14,15 +14,15 @@ HTTP Swagger document generation plugin for cloudwego/cwgo & hertz.
 
 #### Annotation Explanation
 
-| Annotation     | Explanation                                                                            |  
-|----------------|----------------------------------------------------------------------------------------|
-| `api.query`    | `api.query` corresponds to `parameter` with `in: query`                                |  
-| `api.path`     | `api.path` corresponds to `parameter` with `in: path`, required is true                |
-| `api.header`   | `api.header` corresponds to `parameter` with `in: header`                              |       
-| `api.cookie`   | `api.cookie` corresponds to `parameter` with `in: cookie`                              |
-| `api.body`     | `api.body` corresponds to `requestBody` with `content`: `application/json`             | 
-| `api.form`     | `api.form` corresponds to `requestBody` with `content`: `multipart/form-data`          | 
-| `api.raw_body` | `api.raw_body` corresponds to `requestBody` with `content`: `application/octet-stream` | 
+| Annotation     | Explanation                                                                                                          |  
+|----------------|----------------------------------------------------------------------------------------------------------------------|
+| `api.query`    | `api.query` corresponds to `parameter` with `in: query`                                                              |  
+| `api.path`     | `api.path` corresponds to `parameter` with `in: path`, required is true                                              |
+| `api.header`   | `api.header` corresponds to `parameter` with `in: header`                                                            |       
+| `api.cookie`   | `api.cookie` corresponds to `parameter` with `in: cookie`                                                            |
+| `api.body`     | `api.body` corresponds to `requestBody` with `content`: `application/json`                                           | 
+| `api.form`     | `api.form` corresponds to `requestBody` with `content`: `multipart/form-data` or `application/x-www-form-urlencoded` | 
+| `api.raw_body` | `api.raw_body` corresponds to `requestBody` with `content`: `text/plain`                                             | 
 
 ### Response Specification
 
@@ -31,28 +31,28 @@ HTTP Swagger document generation plugin for cloudwego/cwgo & hertz.
 
 #### Annotation Explanation
 
-| Annotation     | Explanation                                                                         |  
-|----------------|-------------------------------------------------------------------------------------|
-| `api.header`   | `api.header` corresponds to `response` with `header`                                |
-| `api.body`     | `api.body` corresponds to `response` with `content`: `application/json`             |
-| `api.raw_body` | `api.raw_body` corresponds to `response` with `content`: `application/octet-stream` |
+| Annotation     | Explanation                                                             |  
+|----------------|-------------------------------------------------------------------------|
+| `api.header`   | `api.header` corresponds to `response` with `header`                    |
+| `api.body`     | `api.body` corresponds to `response` with `content`: `application/json` |
+| `api.raw_body` | `api.raw_body` corresponds to `response` with `content`: `text/plain`   |
 
 ### Method Specification
 
 1. Each `method` is associated with a `pathItem` through an annotation.
 
 #### Annotation Explanation
 
-| Annotation    | Explanation                                                   |  
-|---------------|---------------------------------------------------------------|
-| `api.get`     | `api.get` corresponds to GET request, only `parameters `      |
-| `api.put`     | `api.put` corresponds to PUT request                          |
-| `api.post`    | `api.post` corresponds to POST request                        |
-| `api.patch`   | `api.patch` corresponds to PATCH request                      |
-| `api.delete`  | `api.delete` corresponds to DELETE request, only `parameters` |
-| `api.options` | `api.options` corresponds to OPTIONS request                  |
-| `api.head`    | `api.head` corresponds to HEAD request, only `parameters`     |
-| `api.baseurl` | `api.baseurl` corresponds to `server` `url` of `pathItem`     |
+| Annotation    | Explanation                                                                                       |  
+|---------------|---------------------------------------------------------------------------------------------------|
+| `api.get`     | `api.get` corresponds to GET request, only `parameters `                                          |
+| `api.put`     | `api.put` corresponds to PUT request                                                              |
+| `api.post`    | `api.post` corresponds to POST request                                                            |
+| `api.patch`   | `api.patch` corresponds to PATCH request                                                          |
+| `api.delete`  | `api.delete` corresponds to DELETE request, only `parameters`                                     |
+| `api.options` | `api.options` corresponds to OPTIONS request                                                      |
+| `api.head`    | `api.head` corresponds to HEAD request, only `parameters`                                         |
+| `api.baseurl` | `api.baseurl` corresponds to `server` `url` of `pathItem`, This annotation is not supported by hz |
 
 ### Service Specification
 
@@ -90,6 +90,12 @@ go install github.com/hertz-contrib/swagger-generate/protoc-gen-http-swagger@lat
 protoc-gen-http-swagger --version
 ```
 
+## Usage
+
+```sh
+protoc --http-swagger_out=doc -I idl hello.proto
+```
+
 ## More info
 
 See [examples](example/idl/hello.proto)
diff --git a/protoc-gen-http-swagger/README_CN.md b/protoc-gen-http-swagger/README_CN.md
@@ -2,7 +2,7 @@
 
 [English](README.md) | 中文
 
-适用于 cloudwego/cwgo & hertz 的 http swagger 文档生成插件。
+适用于 [cloudwego/cwgo](https://github.com/cloudwego/cwgo) & [hertz](https://github.com/cloudwego/hertz) 的 http swagger 文档生成插件。
 
 ## 支持的 hz 注解
 
@@ -14,15 +14,15 @@
 
 #### 注解说明
 
-| 注解             | 说明                                                                       |  
-|----------------|--------------------------------------------------------------------------|
-| `api.query`    | `api.query` 对应 `parameter` 中 `in: query` 参数                              |  
-| `api.path`     | `api.path` 对应 `parameter` 中 `in: path` 参数, `required` 为 `true`           |
-| `api.header`   | `api.header` 对应 `parameter` 中 `in: header` 参数                            |       
-| `api.cookie`   | `api.cookie` 对应 `parameter` 中 `in: cookie` 参数                            |
-| `api.body`     | `api.body` 对应 `requestBody` 中 `content` 为 `application/json`             | 
-| `api.form`     | `api.form` 对应 `requestBody` 中 `content` 为 `multipart/form-data`          | 
-| `api.raw_body` | `api.raw_body` 对应 `requestBody` 中 `content` 为 `application/octet-stream` |
+| 注解             | 说明                                                                                                    |  
+|----------------|-------------------------------------------------------------------------------------------------------|
+| `api.query`    | `api.query` 对应 `parameter` 中 `in: query` 参数                                                           |  
+| `api.path`     | `api.path` 对应 `parameter` 中 `in: path` 参数, `required` 为 `true`                                        |
+| `api.header`   | `api.header` 对应 `parameter` 中 `in: header` 参数                                                         |       
+| `api.cookie`   | `api.cookie` 对应 `parameter` 中 `in: cookie` 参数                                                         |
+| `api.body`     | `api.body` 对应 `requestBody` 中 `content` 为 `application/json`                                          | 
+| `api.form`     | `api.form` 对应 `requestBody` 中 `content` 为 `multipart/form-data` 或 `application/x-www-form-urlencoded` | 
+| `api.raw_body` | `api.raw_body` 对应 `requestBody` 中 `content` 为 `text/plain`                                            |
 
 ### Response 规范
 
@@ -31,28 +31,28 @@
 
 #### 注解说明
 
-| 注解             | 说明                                                                    |  
-|----------------|-----------------------------------------------------------------------|
-| `api.header`   | `api.header` 对应 `response` 中 `header`                                 |
-| `api.body`     | `api.body` 对应 `response` 中 `content` 为 `application/json`             |
-| `api.raw_body` | `api.raw_body` 对应 `response` 中 `content` 为 `application/octet-stream` |
+| 注解             | 说明                                                        |  
+|----------------|-----------------------------------------------------------|
+| `api.header`   | `api.header` 对应 `response` 中 `header`                     |
+| `api.body`     | `api.body` 对应 `response` 中 `content` 为 `application/json` |
+| `api.raw_body` | `api.raw_body` 对应 `response` 中 `content` 为 `text/plain`   |
 
 ### Method 规范
 
 1. 每个 `method` 通过注解来关联 `pathItem`
 
 #### 注解说明
 
-| 注解            | 说明                                             |  
-|---------------|------------------------------------------------|
-| `api.get`     | `api.get` 对应 `GET` 请求，只有 `parameter`           |
-| `api.put`     | `api.put` 对应 `PUT` 请求                          |
-| `api.post`    | `api.post` 对应 `POST` 请求                        |
-| `api.patch`   | `api.patch` 对应 `PATCH` 请求                      |
-| `api.delete`  | `api.delete` 对应 `DELETE` 请求，只有 `parameter`     |
-| `api.options` | `api.options` 对应 `OPTIONS` 请求                  |
-| `api.head`    | `api.head` 对应 `HEAD` 请求，只有 `parameter`         |
-| `api.baseurl` | `api.baseurl` 对应 `pathItem` 的 `server` 的 `url` |
+| 注解            | 说明                                                      |  
+|---------------|---------------------------------------------------------|
+| `api.get`     | `api.get` 对应 `GET` 请求，只有 `parameter`                    |
+| `api.put`     | `api.put` 对应 `PUT` 请求                                   |
+| `api.post`    | `api.post` 对应 `POST` 请求                                 |
+| `api.patch`   | `api.patch` 对应 `PATCH` 请求                               |
+| `api.delete`  | `api.delete` 对应 `DELETE` 请求，只有 `parameter`              |
+| `api.options` | `api.options` 对应 `OPTIONS` 请求                           |
+| `api.head`    | `api.head` 对应 `HEAD` 请求，只有 `parameter`                  |
+| `api.baseurl` | `api.baseurl` 对应 `pathItem` 的 `server` 的 `url`, 非hz支持注解 |
 
 ### Service 规范
 
@@ -91,6 +91,12 @@ go install github.com/hertz-contrib/swagger-generate/protoc-gen-http-swagger@lat
 protoc-gen-http-swagger --version
 ```
 
+## 使用
+
+```sh
+protoc --http-swagger_out=doc -I idl hello.proto
+```
+
 ## 更多信息
 
 查看 [示例](example/idl/hello.proto)

diff --git a/protoc-gen-http-swagger/example/doc/openapi.yaml b/protoc-gen-http-swagger/example/doc/openapi.yaml
@@ -42,7 +42,7 @@ paths:
                     content:
                         application/json:
                             schema:
-                                $ref: '#/components/schemas/HelloResp'
+                                $ref: '#/components/schemas/HelloRespBody'
         servers:
             - url: http://127.0.0.1:8888
     /form:
@@ -66,6 +66,20 @@ paths:
                                 form2:
                                     $ref: '#/components/schemas/FormReq_InnerForm'
                             description: Hello - request
+                    application/x-www-form-urlencoded:
+                        schema:
+                            title: Hello - request
+                            required:
+                                - form1
+                            type: object
+                            properties:
+                                form1:
+                                    title: this is an override field schema title
+                                    maxLength: 255
+                                    type: string
+                                form2:
+                                    $ref: '#/components/schemas/FormReq_InnerForm'
+                            description: Hello - request
             responses:
                 "200":
                     description: HelloResp描述
@@ -76,7 +90,7 @@ paths:
                     content:
                         application/json:
                             schema:
-                                $ref: '#/components/schemas/HelloResp'
+                                $ref: '#/components/schemas/HelloRespBody'
         servers:
             - url: http://127.0.0.1:8888
     /hello1:
@@ -117,7 +131,7 @@ paths:
                     content:
                         application/json:
                             schema:
-                                $ref: '#/components/schemas/HelloResp'
+                                $ref: '#/components/schemas/HelloRespBody'
         servers:
             - url: http://127.0.0.1:8888
     /hello2:
@@ -160,7 +174,7 @@ paths:
                     content:
                         application/json:
                             schema:
-                                $ref: '#/components/schemas/HelloResp'
+                                $ref: '#/components/schemas/HelloRespBody'
         servers:
             - url: http://127.0.0.1:8889
     /path{path1}:
@@ -185,7 +199,7 @@ paths:
                     content:
                         application/json:
                             schema:
-                                $ref: '#/components/schemas/HelloResp'
+                                $ref: '#/components/schemas/HelloRespBody'
         servers:
             - url: http://127.0.0.1:8888
 components:
@@ -196,7 +210,7 @@ components:
                 form3:
                     type: string
             description: 内嵌message描述
-        HelloResp:
+        HelloRespBody:
             title: Hello - response
             required:
                 - body

diff --git a/protoc-gen-http-swagger/generator/generator.go b/protoc-gen-http-swagger/generator/generator.go
@@ -495,11 +495,22 @@ func (g *OpenAPIGenerator) buildOperation(
 					},
 				},
 			})
+
+			additionalProperties = append(additionalProperties, &openapi.NamedMediaType{
+				Name: "application/x-www-form-urlencoded",
+				Value: &openapi.MediaType{
+					Schema: &openapi.SchemaOrReference{
+						Oneof: &openapi.SchemaOrReference_Schema{
+							Schema: formSchema,
+						},
+					},
+				},
+			})
 		}
 
 		if len(rawBodySchema.Properties.AdditionalProperties) > 0 {
 			additionalProperties = append(additionalProperties, &openapi.NamedMediaType{
-				Name: "application/octet-stream",
+				Name: "text/plain",
 				Value: &openapi.MediaType{
 					Schema: &openapi.SchemaOrReference{
 						Oneof: &openapi.SchemaOrReference_Schema{
@@ -634,7 +645,7 @@ func (g *OpenAPIGenerator) getResponseForMessage(d *openapi.Document, message *p
 		ref := "#/components/schemas/" + g.reflect.formatMessageName(message.Desc) + "RawBody"
 		g.addSchemaToDocument(d, refSchema)
 		additionalProperties = append(additionalProperties, &openapi.NamedMediaType{
-			Name: "application/octet-stream",
+			Name: "text/plain",
 			Value: &openapi.MediaType{
 				Schema: &openapi.SchemaOrReference{
 					Oneof: &openapi.SchemaOrReference_Reference{

diff --git a/protoc-gen-http-swagger/main.go b/protoc-gen-http-swagger/main.go
@@ -47,7 +47,7 @@ var flags flag.FlagSet
 
 func main() {
 	conf := generator.Configuration{
-		Version:        flags.String("version", "0.0.1", "version number text, e.g. 1.2.3"),
+		Version:        flags.String("version", "3.0.3", "version number text, e.g. 1.2.3"),
 		Title:          flags.String("title", "", "name of the API"),
 		Description:    flags.String("description", "", "description of the API"),
 		Naming:         flags.String("naming", "json", `naming convention. Use "proto" for passing names directly from the proto files`),