Skip to content

Commit

Permalink
feat: metainfo for rpc debugging
Browse files Browse the repository at this point in the history
  • Loading branch information
@EZ4Jam1n
EZ4Jam1n committed Aug 21, 2024
1 parent 783b0fb commit 5ea3430
Show file tree
Hide file tree
Showing 7 changed files with 346 additions and 684 deletions.
116 changes: 37 additions & 79 deletions thrift-gen-rpc-swagger/README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -4,78 +4,10 @@ English | [中文](README_CN.md)

This is a plugin for generating RPC Swagger documentation and providing Swagger-UI access and debugging for [cloudwego/cwgo](https://github.com/cloudwego/cwgo) & [kitex](https://github.com/cloudwego/kitex).

## Supported Annotations

### Request Specifications

1. Interface request fields need to be associated with certain HTTP parameters and parameter names using annotations. Fields without annotations will not be processed.
2. The `method` request `message` is used to generate the `parameters` and `requestBody` for `operation` in Swagger.
3. If the HTTP request uses `GET`, `HEAD`, or `DELETE` methods, the `api.body` annotation in the `request` definition will be invalid, and only `api.query`, `api.path`, `api.cookie`, and `api.header` will be valid.

#### Annotation Descriptions

| Annotation | Description |
|----------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| `api.query` | `api.query` corresponds to the `in: query` parameter in `parameter`, supports basic types and `list` (but not `object` or `map`) |
| `api.path` | `api.path` corresponds to the `in: path` parameter in `parameter`, `required` is `true`, supports basic types |
| `api.header` | `api.header` corresponds to the `in: header` parameter in `parameter`, supports basic types and `list` |
| `api.cookie` | `api.cookie` corresponds to the `in: cookie` parameter in `parameter`, supports basic types |
| `api.body` | `api.body` corresponds to the `content` in `requestBody` as `application/json` |
| `api.form` | `api.form` corresponds to the `content` in `requestBody` as `multipart/form-data` or `application/x-www-form-urlencoded`, reserved for future use, Kitex not yet supported |
| `api.raw_body` | `api.raw_body` corresponds to the `content` in `requestBody` as `text/plain` |

### Response Specifications

1. Interface response fields need to be associated with certain HTTP parameters and parameter names using annotations. Fields without annotations will not be processed.
2. The `method` response `message` is used to generate the `responses` for `operation` in Swagger.

#### Annotation Descriptions

| Annotation | Description |
|--------------|---------------------------------------------------------------------------------------------------------|
| `api.header` | `api.header` corresponds to `header` in `response`, supports only basic types and comma-separated lists |
| `api.body` | `api.body` corresponds to the `content` in `response` as `application/json` |

### Method Specifications

1. Each `method` is associated with a `pathItem` using annotations.

#### Annotation Descriptions

| Annotation | Description |
|---------------|------------------------------------------------------------------------------------------|
| `api.get` | `api.get` corresponds to a `GET` request, only `parameter` is used |
| `api.put` | `api.put` corresponds to a `PUT` request |
| `api.post` | `api.post` corresponds to a `POST` request |
| `api.patch` | `api.patch` corresponds to a `PATCH` request |
| `api.delete` | `api.delete` corresponds to a `DELETE` request, only `parameter` is used |
| `api.baseurl` | `api.baseurl` corresponds to the `url` of `server` in `pathItem`, not a Kitex annotation |

### Service Specifications

#### Annotation Descriptions

| Annotation | Description |
|-------------------|--------------------------------------------------------------------------------|
| `api.base_domain` | `api.base_domain` corresponds to the `url` of `server`, not a Kitex annotation |

## openapi Annotations

| Annotation | Used For | Description |
|---------------------|----------|----------------------------------------------------------------------------------|
| `openapi.operation` | Method | Used to supplement the `operation` in `pathItem` |
| `openapi.property` | Field | Used to supplement the `property` in `schema` |
| `openapi.schema` | Struct | Used to supplement the `schema` in `requestBody` and `response` |
| `openapi.document` | Service | Used to supplement the Swagger documentation, add this annotation to any service |
| `openapi.parameter` | Field | Used to supplement `parameter` |

For more usage examples, please refer to the [example](example/hello.thrift).

## Installation

```sh

# Install from official repository
# Install from the official repository

git clone https://github.com/hertz-contrib/swagger-generate
cd thrift-gen-rpc-swagger
Expand All @@ -93,25 +25,51 @@ thrift-gen-rpc-swagger --version
### Generate Swagger Documentation

```sh

thriftgo -g go -p rpc-swagger:OutputDir=./output,HertzAddr=127.0.0.1:8080,KitexAddr=127.0.0.1:8888 hello.thrift

```

### Start the Swagger-UI Service

```sh

go run ./output/swagger.go
```

### Access Swagger-UI (Kitex service needs to be running for debugging)

```sh
http://127.0.0.1:8080/swagger/index.html
```

## Additional Information
## Usage Instructions

### Debugging Instructions
1. The plugin generates Swagger documentation and also creates an HTTP (Hertz) service to provide access and debugging of the Swagger documentation.
2. To access the Swagger documentation, start `swagger.go`. The HTTP service address can be specified via the `HertzAddr` parameter, which defaults to 127.0.0.1:8080. Ensure that the `server` URL in the Swagger documentation matches `HertzAddr` for debugging purposes. After starting, access `/swagger/index.html`.
3. To debug the Swagger documentation, the Kitex service must also be running. The `KitexAddr` parameter specifies the Kitex service address, which defaults to 127.0.0.1:8888. Ensure that this matches the actual Kitex service address.

### Generation Instructions
1. All RPC methods will be converted to HTTP POST methods. The request parameters correspond to the request body, with the content type being `application/json`. The response is handled similarly.
2. Annotations can be used to supplement information in the Swagger documentation, such as `openapi.operation`, `openapi.property`, `openapi.schema`, `api.base_domain`, and `api.baseurl`.
3. To use the `openapi.operation`, `openapi.property`, `openapi.schema`, and `openapi.document` annotations, you need to import `openapi.thrift`.

1. The plugin generates Swagger documentation and an HTTP (Hertz) service for accessing and debugging the Swagger documentation.
2. To access the Swagger documentation, you need to start the `swagger.go` HTTP service. The address of the service can be specified using the `HertzAddr` parameter, defaulting to 127.0.0.1:8080. The `server` in the Swagger documentation must match the `HertzAddr` for debugging to work, visit /swagger/index.html after startup.
3. To debug the Swagger documentation, you also need to start the Kitex service. The `KitexAddr` parameter specifies the address of the Kitex service, defaulting to 127.0.0.1:8888. This address must match the actual Kitex service address.
4. Debugging RPC services is based on Kitex's HTTP generic calls. For more information, please refer to [Kitex Generic Calls](https://www.cloudwego.io/en/docs/kitex/tutorials/advanced-feature/generic-call/thrift_idl_annotation_standards/).
### Metadata Passing
1. Metadata passing is supported. The plugin generates a `theader` query parameter for each method by default, used for metadata transmission. The format should be in JSON, e.g., `{"p_k":"p_v","k":"v"}`.
2. For single-hop metadata passthrough, the format is `"key":"value"`.
3. For continuous metadata passthrough, the format is `"p_key":"value"`, with the `p_` prefix added.
4. Reverse metadata passthrough is supported. If set, metadata can be viewed in the response, attached in the format `"key":"value"`.
5. For more information on using metadata, please refer to [Metainfo](https://www.cloudwego.io/en/docs/kitex/tutorials/advanced-feature/metainfo/).

## More Information
## Supported Annotations

| Annotation | Component | Description |
|---------------------|-----------|--------------------------------------------------------------------------------------------------------|
| `openapi.operation` | Method | Used to supplement the `operation` of a `pathItem` |
| `openapi.property` | Field | Used to supplement the `property` of a `schema` |
| `openapi.schema` | Struct | Used to supplement the `schema` of a `requestBody` and `response` |
| `openapi.document` | Service | Used to supplement the Swagger document; can be added in any service |
| `api.base_domain` | Service | Corresponds to the `url` of the `server`, used to specify the service's URL |
| `api.baseurl` | Method | Corresponds to the `url` of the `server` for a `pathItem`, used to specify the URL for a single method |

## Additional Information

See the [example](example/hello.thrift).
For more usage details, please refer to the [example](example/hello.thrift).
107 changes: 35 additions & 72 deletions thrift-gen-rpc-swagger/README_CN.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -4,73 +4,6 @@

适用于 [cloudwego/cwgo](https://github.com/cloudwego/cwgo) & [kitex](https://github.com/cloudwego/kitex) 的 rpc swagger 文档生成及 swagger-ui 访问调试插件。

## 支持的注解

### Request 规范

1. 接口请求字段需要使用注解关联到 HTTP 的某类参数和参数名称, 没有注解的字段不做处理。
2. 根据 `method` 中的请求 `message` 生成 swagger 中 `operation` 的 `parameters` 和 `requestBody`。
3. 如果 HTTP 请求是采用 `GET`、`HEAD`、`DELETE` 方式的，那么 `request` 定义中出现的 `api.body` 注解无效，只有`api.query`, `api.path`, `api.cookie`, `api.header` 有效。

#### 注解说明

| 注解 | 说明 |
|----------------|----------------------------------------------------------------------------------------------------------------------|
| `api.query` | `api.query` 对应 `parameter` 中 `in: query` 参数, 支持基本类型和`list`(`object`, `map`暂不支持） |
| `api.path` | `api.path` 对应 `parameter` 中 `in: path` 参数, `required` 为 `true`, 支持基本类型 |
| `api.header` | `api.header` 对应 `parameter` 中 `in: header` 参数, 支持基本类型和`list` |
| `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`, 预留, Kitex暂不支持 |
| `api.raw_body` | `api.body` 对应 `requestBody` 中 `content` 为 `text/plain` |

### Response 规范

1. 接口响应字段需要使用注解关联到 HTTP 的某类参数和参数名称, 没有注解的字段不做处理。
2. 根据 `method` 中的响应 `message` 生成 swagger 中 `operation` 的 `responses`。

#### 注解说明

| 注解 | 说明 |
|----------------|-----------------------------------------------------------|
| `api.header` | `api.header` 对应 `response` 中 `header`, 只支持基本类型和逗号分隔的list |
| `api.body` | `api.body` 对应 `response` 中 `content` 为 `application/json` |

### 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.baseurl` | `api.baseurl` 对应 `pathItem` 的 `server` 的 `url`, 非 Kitex 注解 |

### Service 规范

#### 注解说明

| 注解 | 说明 |
|-------------------|---------------------------------------------------|
| `api.base_domain` | `api.base_domain` 对应 `server` 的 `url`, 非 Kitex 注解 |

## openapi 注解

| 注解 | 使用组件 | 说明 |
|---------------------|---------|--------------------------------------------|
| `openapi.operation` | Method | 用于补充 `pathItem` 的 `operation` |
| `openapi.property` | Field | 用于补充 `schema` 的 `property` |
| `openapi.schema` | Struct | 用于补充 `requestBody` 和 `response` 的 `schema` |
| `openapi.document` | Service | 用于补充 swagger 文档，任意service中添加该注解即可 |
| `openapi.parameter` | Field | 用于补充 `parameter` |

更多的使用方法请参考 [示例](example/hello.thrift)

## 安装

```sh
Expand Down Expand Up @@ -105,16 +38,46 @@ go run ./output/swagger.go

```

## 补充说明
### 访问 swagger-ui (调试需启动Kitex服务)

```sh

http://127.0.0.1:8080/swagger/index.html
```

## 使用说明

### 调试说明
1. 插件会生成 swagger 文档，并且会生成一个 http (Hertz) 服务, 用于提供 swagger 文档的访问及调试。
2. swagger 文档的访问需启动 swagger.go, http 服务的地址可以通过参数 `HertzAddr` 参数指定, 默认为127.0.0.1:8080, 需要保持 swagger 文档中的 `server` 与 `HertzAddr` 一致才可以调试, 启动后访问访问/swagger/index.html。
3. swagger 文档的调试还需启动 Kitex 服务, `KitexAddr`用于指定 Kitex 服务的地址, 默认为127.0.0.1:8888, 需要保持与实际的 Kitex 服务地址一致。
4. 对 rpc 服务的调试基于 Kitex 的 http 泛化调用, 更多的信息请参考 [Kitex泛化调用](https://www.cloudwego.io/zh/docs/kitex/tutorials/advanced-feature/generic-call/thrift_idl_annotation_standards/)。
2. swagger 文档的访问需启动 swagger.go, http 服务的地址可以通过参数 `HertzAddr` 参数指定, 默认为 127.0.0.1:8080, 需要保持 swagger 文档中 `server` 的 url 与 `HertzAddr` 一致才可以调试, 启动后访问访问/swagger/index.html。
3. swagger 文档的调试还需启动 Kitex 服务, `KitexAddr`用于指定 Kitex 服务的地址, 默认为 127.0.0.1:8888, 需要保持与实际的 Kitex 服务地址一致。

### 生成说明
1. 所有的 rpc 方法会转换成 http 的 post 方法，请求参数对应 Request body, content 类型为 application/json 格式，返回值同上。
2. 可通过注解来补充 swagger 文档的信息，如 `openapi.operation`, `openapi.property`, `openapi.schema`, `api.base_domain`, `api.baseurl`。
3. 如需使用`openapi.operation`, `openapi.property`, `openapi.schema`, `openpai.document` 注解，需引用 openapi.thrift。

### 元信息传递
1. 支持元信息传递, 插件默认为每个方法生成一个`theader`的查询参数, 用于传递元信息, 格式需满足 json 格式, 如{"p_k":"p_v","k":"v"}。
2. 单跳透传元信息, 格式为 "key":"value"。
3. 持续透传元信息, 格式为 "p_key":"value", 需添加前缀`p_`。
4. 支持反向透传元信息, 若设置则可在返回值中查看到元信息, 返回通过"key":"value"的格式附加在响应中。
5. 更多使用元信息可参考 [Metainfo](https://www.cloudwego.io/zh/docs/kitex/tutorials/advanced-feature/metainfo/)。

## 支持的注解

| 注解 | 使用组件 | 说明 |
|---------------------|---------|-------------------------------------------------------|
| `openapi.operation` | Method | 用于补充 `pathItem` 的 `operation` |
| `openapi.property` | Field | 用于补充 `schema` 的 `property` |
| `openapi.schema` | Struct | 用于补充 `requestBody` 和 `response` 的 `schema` |
| `openapi.document` | Service | 用于补充 swagger 文档，任意 service 中添加该注解即可 |
| `api.base_domain` | Service | 对应 `server` 的 `url`, 用于指定 service 服务的 url |
| `api.baseurl` | Method | 对应 `pathItem` 的 `server` 的 `url`, 用于指定单个 method 的 url |

## 更多信息

查看 [示例](example/hello.thrift)
更多的使用方法请参考 [示例](example/hello.thrift)



Expand Down
Loading

0 comments on commit 5ea3430

Please sign in to comment.