README_CN.md

Swagger Generate

English | 中文

Swagger Generate 是一个为 HTTP 和 RPC 服务生成 Swagger 文档及 Swagger-UI 访问调试的插件集合。该项目适用于 CloudWeGo 生态下的 Cwgo、 Hertz 和 Kitex 框架。它提供了一套便捷的工具来帮助开发者自动生成 Swagger 文档，从而简化 API 文档编写及调试过程。

包含的插件

• protoc-gen-http-swagger：为基于 Protobuf 的 HTTP 服务生成 Swagger 文档和 Swagger UI 进行调试。
• thrift-gen-http-swagger：为基于 Thrift 的 HTTP 服务生成 Swagger 文档和 Swagger UI 进行调试。
• protoc-gen-rpc-swagger：为基于 Protobuf 的 RPC 服务生成 Swagger 文档和 Swagger UI 进行调试。
• thrift-gen-rpc-swagger：为基于 Thrift 的 RPC 服务生成 Swagger 文档和 Swagger UI 进行调试。

项目优势

• 自动化生成：支持通过 Protobuf 和 Thrift 文件生成完整的 Swagger 文档，简化了 API 文档的维护。
• 集成调试：生成的 Swagger UI 能直接用于调试服务，支持 HTTP 和 RPC 两种模式。
• Hertz 和 Kitex 集成：为 Hertz 和 Kitex 提供了无缝的文档生成和调试支持。
• 灵活的注解支持：允许通过注解扩展生成的 Swagger 文档内容，支持 openapi.operation、openapi.schema 等 OpenAPI 注解。

安装

可以通过以下方式安装各个插件：

# 官方仓库安装
git clone https://github.com/hertz-contrib/swagger-generate
cd <plugin-directory>
go install

# 直接安装
go install github.com/hertz-contrib/swagger-generate/<plugin-name>@latest

使用示例

生成 HTTP Swagger 文档

对于基于 Protobuf 的 HTTP 服务：

protoc --http-swagger_out=swagger -I idl hello.proto

对于基于 Thrift 的 HTTP 服务：

thriftgo -g go -p http-swagger hello.thrift

生成 RPC Swagger 文档

对于基于 Protobuf 的 RPC 服务：

protoc --rpc-swagger_out=swagger -I idl idl/hello.proto

对于基于 Thrift 的 RPC 服务：

thriftgo -g go -p rpc-swagger hello.thrift

在 Hertz 或 Kitex 服务中集成 Swagger-UI

在 Hertz 服务中：

func main() {
    h := server.Default()
    swagger.BindSwagger(h) //增加改行
    register(h)
    h.Spin()
}

或者

func register(r *server.Hertz) {
    swagger.BindSwagger(r) //增加改行
    
    router.GeneratedRegister(r)
    
    customizedRegister(r)
}

在 Kitex 服务中：

func main() {
	svr := example.NewServer(new(HelloService1Impl), server.WithTransHandlerFactory(&swagger.MixTransHandlerFactory{})) //改动改行

	err := svr.Run()

	if err != nil {
		log.Println(err.Error())
	}
}

请参考 kitex_swagger_gen 和 hertz_swagger_gen 获取更多使用场景示例。

更多信息

请参考各个插件的 readme 文档获取更多使用细节。