diff --git a/thrift-gen-http-swagger/README.md b/thrift-gen-http-swagger/README.md index b5fe804..36b1534 100644 --- a/thrift-gen-http-swagger/README.md +++ b/thrift-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,11 +31,11 @@ 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 @@ -43,16 +43,16 @@ HTTP Swagger document generation plugin for cloudwego/cwgo & hertz. #### 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 diff --git a/thrift-gen-http-swagger/README_CN.md b/thrift-gen-http-swagger/README_CN.md index 45e2d56..92cd173 100644 --- a/thrift-gen-http-swagger/README_CN.md +++ b/thrift-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,11 +31,11 @@ #### 注解说明 -| 注解 | 说明 | -|----------------|-----------------------------------------------------------------------| -| `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 规范 @@ -43,16 +43,16 @@ #### 注解说明 -| 注解 | 说明 | -|---------------|------------------------------------------------| -| `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 规范 diff --git a/thrift-gen-http-swagger/example/docs/openapi.yaml b/thrift-gen-http-swagger/example/docs/openapi.yaml index a50997f..f2d558e 100644 --- a/thrift-gen-http-swagger/example/docs/openapi.yaml +++ b/thrift-gen-http-swagger/example/docs/openapi.yaml @@ -43,7 +43,7 @@ paths: content: application/json: schema: - $ref: '#/components/schemas/HelloResp' + $ref: '#/components/schemas/HelloRespBody' servers: - url: http://127.0.0.1:8888 /form: @@ -68,6 +68,20 @@ paths: form3: $ref: '#/components/schemas/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 + form3: + $ref: '#/components/schemas/InnerForm' + description: Hello - request responses: "200": description: HelloResp @@ -78,7 +92,7 @@ paths: content: application/json: schema: - $ref: '#/components/schemas/HelloResp' + $ref: '#/components/schemas/HelloRespBody' servers: - url: http://127.0.0.1:8888 /hello1: @@ -105,7 +119,7 @@ paths: - name: query1 in: query description: |- - 对于map类型调试时需要转义才能解析，如下所示 + 对于parameters中的map类型调试时需要转义才能解析，如下所示 { "query1": "{\"key\":\"value\"}" } @@ -123,7 +137,7 @@ paths: content: application/json: schema: - $ref: '#/components/schemas/HelloResp' + $ref: '#/components/schemas/HelloRespBody' servers: - url: http://127.0.0.1:8888 /hello2: @@ -152,7 +166,7 @@ paths: - name: query1 in: query description: |- - 对于map类型调试时需要转义才能解析，如下所示 + 对于parameters中的map类型调试时需要转义才能解析，如下所示 { "query1": "{\"key\":\"value\"}" } @@ -170,7 +184,7 @@ paths: content: application/json: schema: - $ref: '#/components/schemas/HelloResp' + $ref: '#/components/schemas/HelloRespBody' servers: - url: http://127.0.0.1:8889 /path{path1}: @@ -195,12 +209,12 @@ paths: content: application/json: schema: - $ref: '#/components/schemas/HelloResp' + $ref: '#/components/schemas/HelloRespBody' servers: - url: http://127.0.0.1:8888 components: schemas: - HelloResp: + HelloRespBody: title: Hello - response required: - body diff --git a/thrift-gen-http-swagger/generator/generator.go b/thrift-gen-http-swagger/generator/generator.go index 0ac4ad8..67a934a 100644 --- a/thrift-gen-http-swagger/generator/generator.go +++ b/thrift-gen-http-swagger/generator/generator.go @@ -438,11 +438,20 @@ func (g *OpenAPIGenerator) buildOperation( }, }, }) + + additionalProperties = append(additionalProperties, &openapi.NamedMediaType{ + Name: "application/x-www-form-urlencoded", + Value: &openapi.MediaType{ + Schema: &openapi.SchemaOrReference{ + 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{ Schema: rawBodySchema, @@ -594,7 +603,7 @@ func (g *OpenAPIGenerator) getResponseForStruct(d *openapi.Document, desc *thrif ref := "#/components/schemas/" + desc.GetName() + "RawBody" g.addSchemaToDocument(d, refSchema) additionalProperties = append(additionalProperties, &openapi.NamedMediaType{ - Name: "application/octet-stream", + Name: "text/plain", Value: &openapi.MediaType{ Schema: &openapi.SchemaOrReference{ Reference: &openapi.Reference{Xref: ref},