diff --git a/content/en/docs/hertz/tutorials/third-party/middleware/swagger.md b/content/en/docs/hertz/tutorials/third-party/middleware/swagger.md index fa55f702d6f..a48844dd945 100644 --- a/content/en/docs/hertz/tutorials/third-party/middleware/swagger.md +++ b/content/en/docs/hertz/tutorials/third-party/middleware/swagger.md @@ -1,11 +1,288 @@ --- title: "Swagger" -date: 2022-10-06 +date: 2025-12-04 weight: 8 keywords: ["Swagger", "RESTful API"] description: "Hertz middleware to automatically generate RESTful API documentation with Swagger 2.0." --- +> **⚠️ Deprecated** +> +> The `hertz-contrib/swagger` middleware is now deprecated. +> Hertz recommends all users to migrate to the official `swaggo/swag` toolchain using the [Hertz HTTP Adaptor](../../basic-feature/http-adaptor/). +> +> See the migration guide below. + +## Migration Guide + +1. Remove deprecated dependencies + +```sh +github.com/hertz-contrib/swagger +github.com/swaggo/files +``` + +2. Install official swag generator + +```sh +go install github.com/swaggo/swag/cmd/swag@latest +``` + +3. Replace swagger handler + +If the project has already been set up, replace the code below. + +```go +// Before (using hertz-contrib/swagger) +import "github.com/hertz-contrib/swagger" +import swaggerFiles "github.com/swaggo/files" + +url := swagger.URL("http://localhost:8888/swagger/doc.json") +h.GET("/swagger/*any", swagger.WrapHandler(swaggerFiles.Handler, url)) + +// After (using http adaptor) +import "github.com/cloudwego/hertz/pkg/common/adaptor" +import httpSwagger "github.com/swaggo/http-swagger" + +h.GET("/swagger/*any", adaptor.HertzHandler(httpSwagger.WrapHandler)) +``` + +If starting a new project, follow the sample code below as an example. + +```go +package main + +import ( + "context" + + // Path to generated docs + _ "project/docs" + + "github.com/cloudwego/hertz/pkg/app" + "github.com/cloudwego/hertz/pkg/app/server" + "github.com/cloudwego/hertz/pkg/common/adaptor" + httpSwagger "github.com/swaggo/http-swagger" +) + +// PingHandler handler +// @Summary Summary +// @Description Description +// @Accept application/json +// @Produce application/json +// @Router /ping [get] +func PingHandler(c context.Context, ctx *app.RequestContext) { + ctx.JSON(200, map[string]string{ + "ping": "pong", + }) +} + +// @title HertzTest +// @version 1.0 +// @description This is a demo using Hertz. + +// @contact.name hertz +// @contact.url https://github.com/cloudwego/hertz + +// @license.name Apache 2.0 +// @license.url http://www.apache.org/licenses/LICENSE-2.0.html + +// @host localhost:8888 +// @BasePath / +// @schemes http +func main() { + h := server.Default() + + h.GET("/ping", PingHandler) + + // Swagger endpoint + h.GET("/swagger/*any", + adaptor.HertzHandler( + httpSwagger.WrapHandler, + ), + ) + + h.Spin() +} +``` + +4. Generate Swagger docs + +```sh +swag init +``` + +5. Run program + +Start the Hertz server. + +```sh +go run main.go +``` + +On a web browser, go to http://localhost:8888/swagger/index.html or whichever address that is configured to see the Swagger UI. + +6. Provide custom Swagger UI + +For users who want to create their own custom UI, they will need to download the Swagger UI dist files, and serve the UI files as static assets. +Copy the following files from [swagger-ui/dist](https://github.com/swagger-api/swagger-ui/tree/master/dist) and place them in `swagger-ui/`. +- https://github.com/swagger-api/swagger-ui/blob/master/dist/favicon-16x16.png +- https://github.com/swagger-api/swagger-ui/blob/master/dist/favicon-32x32.png +- https://github.com/swagger-api/swagger-ui/blob/master/dist/swagger-ui.css +- https://github.com/swagger-api/swagger-ui/blob/master/dist/swagger-ui-bundle.js +- https://github.com/swagger-api/swagger-ui/blob/master/dist/swagger-ui-standalone-preset.js + +Create an `index.html` file in the same directory with the following template. The original configuration options present in the old `hertz-contrib/swagger` middleware can be directly configured in the HTML file. + +**Note: The HTML file below is just a sample and should be modified accordingly to the user's needs.** + +```html + + + + + My Custom Swagger UI + + + + + + + + + +
+ My Custom Swagger UI +
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+ + + + + + + +``` + +The final project directory should have the following structure: + +```sh +project/ +├── main.go +├── docs/ # generated by swag init +│ ├── docs.go +│ ├── swagger.json +│ └── swagger.yaml +├── swagger-ui/ # custom UI (copied from Swagger UI dist) +│ ├── favicon-16x16.png +│ ├── favicon-32x32.png +│ ├── index.html +│ ├── swagger-ui-bundle.js +│ ├── swagger-ui-standalone-preset.js +│ ├── swagger-ui.css +│ └── ...other swagger ui dist files as needed... +├── go.mod +└── go.sum +``` + +7. Serve static files + +Add this line into `main.go` + +```go +h.GET("/swagger/*any", adaptor.HertzHandler(httpSwagger.WrapHandler)) + +// Add this line +h.Static("/", "./swagger-ui") + +h.Spin() + +// Rest of code +``` + +8. Run program + +```sh +go run main.go +``` + +On a web browser, go to http://localhost:8888/index.html to see the customised Swagger UI. + +## Legacy Documentation (Deprecated) + Hertz middleware to automatically generate RESTful API documentation with Swagger 2.0. The implementation of the [swagger](https://github.com/hertz-contrib/swagger) extension refers to the implementation of [Gin](https://github.com/swaggo/gin-swagger). diff --git a/content/zh/docs/hertz/tutorials/third-party/middleware/swagger.md b/content/zh/docs/hertz/tutorials/third-party/middleware/swagger.md index ec79c5c943a..3972952964d 100644 --- a/content/zh/docs/hertz/tutorials/third-party/middleware/swagger.md +++ b/content/zh/docs/hertz/tutorials/third-party/middleware/swagger.md @@ -1,11 +1,288 @@ --- title: "Swagger" -date: 2022-10-06 +date: 2025-12-04 weight: 8 keywords: ["Swagger", "RESTful API"] description: "用 Swagger 2.0 来自动生成 RESTful API 文档的 Hertz 中间件。" --- +> **⚠️ 已废弃** +> +> `hertz-contrib.swagger` 中间件已被废弃。 +> Hertz 推荐所有用户迁移到官方 `swaggo/swag` 工具链，使用 [Hertz HTTP Adaptor](../../basic-feature/http-adaptor/)。 +> +> 迁移指南如下。 + +## 迁移指南 + +1. 移除已废弃的依赖项 + +```sh +github.com/hertz-contrib/swagger +github.com/swaggo/files +``` + +2. 安装官方 Swag 生成器 + +```sh +go install github.com/swaggo/swag/cmd/swag@latest +``` + +3. 替换 Swagger handler + +如果项目已经设置好，替换下面的代码。 + +```go +// 旧版本（使用 hertz-contrib/swagger） +import "github.com/hertz-contrib/swagger" +import swaggerFiles "github.com/swaggo/files" + +url := swagger.URL("http://localhost:8888/swagger/doc.json") +h.GET("/swagger/*any", swagger.WrapHandler(swaggerFiles.Handler, url)) + +// 新版本（使用 http adaptor） +import "github.com/cloudwego/hertz/pkg/common/adaptor" +import httpSwagger "github.com/swaggo/http-swagger" + +h.GET("/swagger/*any", adaptor.HertzHandler(httpSwagger.WrapHandler)) +``` + +如果是新项目，请参考以下示例代码： + +```go +package main + +import ( + "context" + + // 生成的 docs 路径 + _ "project/docs" + + "github.com/cloudwego/hertz/pkg/app" + "github.com/cloudwego/hertz/pkg/app/server" + "github.com/cloudwego/hertz/pkg/common/adaptor" + httpSwagger "github.com/swaggo/http-swagger" +) + +// PingHandler +// @Summary Summary +// @Description Description +// @Accept application/json +// @Produce application/json +// @Router /ping [get] +func PingHandler(c context.Context, ctx *app.RequestContext) { + ctx.JSON(200, map[string]string{ + "ping": "pong", + }) +} + +// @title HertzTest +// @version 1.0 +// @description This is a demo using Hertz + +// @contact.name hertz +// @contact.url https://github.com/cloudwego/hertz + +// @license.name Apache 2.0 +// @license.url http://www.apache.org/licenses/LICENSE-2.0.html + +// @host localhost:8888 +// @BasePath / +// @schemes http +func main() { + h := server.Default() + + h.GET("/ping", PingHandler) + + // Swagger endpoint + h.GET("/swagger/*any", + adaptor.HertzHandler( + httpSwagger.WrapHandler, + ), + ) + + h.Spin() +} +``` + +4. 更新 Swagger 注释 + +```sh +swag init +``` + +5. 运行程序 + +启动 Hertz 服务器。 + +```sh +go run main.go +``` + +在浏览器中访问 http://localhost:8888/swagger/index.html 或配置的地址，即可查看 Swagger UI。 + +6. 使用自定义 Swagger UI + +对于想要创建自己的自定义 UI 的用户，他们需要下载 Swagger UI 分发文件，并将 UI 文件作为静态资源提供。 +从 [swagger-ui/dist](https://github.com/swagger-api/swagger-ui/tree/master/dist) 中复制以下文件到 `swagger-ui/` +- https://github.com/swagger-api/swagger-ui/blob/master/dist/favicon-16x16.png +- https://github.com/swagger-api/swagger-ui/blob/master/dist/favicon-32x32.png +- https://github.com/swagger-api/swagger-ui/blob/master/dist/swagger-ui.css +- https://github.com/swagger-api/swagger-ui/blob/master/dist/swagger-ui-bundle.js +- https://github.com/swagger-api/swagger-ui/blob/master/dist/swagger-ui-standalone-preset.js + +在同一目录下创建一个 `index.html` 文件，示例模板如下。旧版 hertz-contrib/swagger 中的配置项都可以直接在 HTML 文件里设置。 + +**注意：以下 HTML 文件仅为示例，应根据用户需求进行修改。** + +```html + + + + + My Custom Swagger UI + + + + + + + + + +
+ My Custom Swagger UI +
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+ + + + + + + +``` + +最终项目结构应如下： + +```sh +project/ +├── main.go +├── docs/ # generated by swag init +│ ├── docs.go +│ ├── swagger.json +│ └── swagger.yaml +├── swagger-ui/ # custom UI (copied from Swagger UI dist) +│ ├── favicon-16x16.png +│ ├── favicon-32x32.png +│ ├── index.html +│ ├── swagger-ui-bundle.js +│ ├── swagger-ui-standalone-preset.js +│ ├── swagger-ui.css +│ └── ...other swagger ui dist files as needed... +├── go.mod +└── go.sum +``` + +7. 提供静态资源服务 + +在 `main.go` 中加入 + +```go +h.GET("/swagger/*any", adaptor.HertzHandler(httpSwagger.WrapHandler)) + +// 加这一行 +h.Static("/", "./swagger-ui") + +h.Spin() + +// 其他代码 +``` + +8. 运行程序 + +```sh +go run main.go +``` + +浏览器访问：http://localhost:8888/index.html 即可查看自定义的 Swagger UI。 + +## 旧版文档（已废弃） + 这是一个用 Swagger 2.0 来自动生成 RESTful API 文档的 Hertz 中间件。 参考了 gin 的 [实现](https://github.com/swaggo/gin-swagger)，对 Hertz 进行了适配。