Skip to content

Commit c69f9aa

Browse files
JoshuahokyJoshuahoky
authored
chore: deprecate docs for swagger (#1472)
1 parent 1adeaf9 commit c69f9aa

File tree

2 files changed

+556
-2
lines changed
  • content
    • en/docs/hertz/tutorials/third-party/middleware
    • zh/docs/hertz/tutorials/third-party/middleware

2 files changed

+556
-2
lines changed

‎content/en/docs/hertz/tutorials/third-party/middleware/swagger.md‎

Lines changed: 278 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,11 +1,288 @@
11
---
22
title: "Swagger"
3-
date: 2022-10-06
3+
date: 2025-12-04
44
weight: 8
55
keywords: ["Swagger", "RESTful API"]
66
description: "Hertz middleware to automatically generate RESTful API documentation with Swagger 2.0."
77
---
88

9+
> **⚠️ Deprecated**
10+
>
11+
> The `hertz-contrib/swagger` middleware is now deprecated.
12+
> Hertz recommends all users to migrate to the official `swaggo/swag` toolchain using the [Hertz HTTP Adaptor](../../basic-feature/http-adaptor/).
13+
>
14+
> See the migration guide below.
15+
16+
## Migration Guide
17+
18+
1. Remove deprecated dependencies
19+
20+
```sh
21+
github.com/hertz-contrib/swagger
22+
github.com/swaggo/files
23+
```
24+
25+
2. Install official swag generator
26+
27+
```sh
28+
go install github.com/swaggo/swag/cmd/swag@latest
29+
```
30+
31+
3. Replace swagger handler
32+
33+
If the project has already been set up, replace the code below.
34+
35+
```go
36+
// Before (using hertz-contrib/swagger)
37+
import "github.com/hertz-contrib/swagger"
38+
import swaggerFiles "github.com/swaggo/files"
39+
40+
url := swagger.URL("http://localhost:8888/swagger/doc.json")
41+
h.GET("/swagger/*any", swagger.WrapHandler(swaggerFiles.Handler, url))
42+
43+
// After (using http adaptor)
44+
import "github.com/cloudwego/hertz/pkg/common/adaptor"
45+
import httpSwagger "github.com/swaggo/http-swagger"
46+
47+
h.GET("/swagger/*any", adaptor.HertzHandler(httpSwagger.WrapHandler))
48+
```
49+
50+
If starting a new project, follow the sample code below as an example.
51+
52+
```go
53+
package main
54+
55+
import (
56+
"context"
57+
58+
// Path to generated docs
59+
_ "project/docs"
60+
61+
"github.com/cloudwego/hertz/pkg/app"
62+
"github.com/cloudwego/hertz/pkg/app/server"
63+
"github.com/cloudwego/hertz/pkg/common/adaptor"
64+
httpSwagger "github.com/swaggo/http-swagger"
65+
)
66+
67+
// PingHandler handler
68+
// @Summary Summary
69+
// @Description Description
70+
// @Accept application/json
71+
// @Produce application/json
72+
// @Router /ping [get]
73+
func PingHandler(c context.Context, ctx *app.RequestContext) {
74+
ctx.JSON(200, map[string]string{
75+
"ping": "pong",
76+
})
77+
}
78+
79+
// @title HertzTest
80+
// @version 1.0
81+
// @description This is a demo using Hertz.
82+
83+
// @contact.name hertz
84+
// @contact.url https://github.com/cloudwego/hertz
85+
86+
// @license.name Apache 2.0
87+
// @license.url http://www.apache.org/licenses/LICENSE-2.0.html
88+
89+
// @host localhost:8888
90+
// @BasePath /
91+
// @schemes http
92+
func main() {
93+
h := server.Default()
94+
95+
h.GET("/ping", PingHandler)
96+
97+
// Swagger endpoint
98+
h.GET("/swagger/*any",
99+
adaptor.HertzHandler(
100+
httpSwagger.WrapHandler,
101+
),
102+
)
103+
104+
h.Spin()
105+
}
106+
```
107+
108+
4. Generate Swagger docs
109+
110+
```sh
111+
swag init
112+
```
113+
114+
5. Run program
115+
116+
Start the Hertz server.
117+
118+
```sh
119+
go run main.go
120+
```
121+
122+
On a web browser, go to http://localhost:8888/swagger/index.html or whichever address that is configured to see the Swagger UI.
123+
124+
6. Provide custom Swagger UI
125+
126+
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.
127+
Copy the following files from [swagger-ui/dist](https://github.com/swagger-api/swagger-ui/tree/master/dist) and place them in `swagger-ui/`.
128+
- https://github.com/swagger-api/swagger-ui/blob/master/dist/favicon-16x16.png
129+
- https://github.com/swagger-api/swagger-ui/blob/master/dist/favicon-32x32.png
130+
- https://github.com/swagger-api/swagger-ui/blob/master/dist/swagger-ui.css
131+
- https://github.com/swagger-api/swagger-ui/blob/master/dist/swagger-ui-bundle.js
132+
- https://github.com/swagger-api/swagger-ui/blob/master/dist/swagger-ui-standalone-preset.js
133+
134+
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.
135+
136+
**Note: The HTML file below is just a sample and should be modified accordingly to the user's needs.**
137+
138+
```html
139+
<!DOCTYPE html>
140+
<html lang="en">
141+
<head>
142+
<meta charset="UTF-8">
143+
<title>My Custom Swagger UI</title> <!-- Title -->
144+
<link href="https://fonts.googleapis.com/css?family=Open+Sans:400,700|Source+Code+Pro:300,600|Titillium+Web:400,600,700" rel="stylesheet">
145+
<link rel="stylesheet" type="text/css" href="swagger-ui.css">
146+
<link rel="icon" type="image/png" href="favicon-32x32.png" sizes="32x32" />
147+
<link rel="icon" type="image/png" href="favicon-16x16.png" sizes="16x16" />
148+
<style>
149+
html { box-sizing: border-box; overflow: -moz-scrollbars-vertical; overflow-y: scroll; }
150+
*, *:before, *:after { box-sizing: inherit; }
151+
152+
body {
153+
margin: 0;
154+
background: #fff4d6;
155+
}
156+
157+
.custom-banner {
158+
padding: 20px;
159+
background: #4f46e5;
160+
color: white;
161+
text-align: center;
162+
font-size: 26px;
163+
font-weight: bold;
164+
border-bottom: 4px solid #312e81;
165+
}
166+
</style>
167+
</head>
168+
169+
<body>
170+
171+
<div class="custom-banner">
172+
My Custom Swagger UI
173+
</div>
174+
175+
<svg xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink" style="position:absolute;width:0;height:0">
176+
<defs>
177+
<symbol viewBox="0 0 20 20" id="unlocked">
178+
<path d="M15.8 8H14V5.6C14 2.703 12.665 1 10 1 7.334 1 6 2.703 6 5.6V6h2v-.801C8 3.754 8.797 3 10 3c1.203 0 2 .754 2 2.199V8H4c-.553 0-1 .646-1 1.199V17c0 .549.428 1.139.951 1.307l1.197.387C5.672 18.861 6.55 19 7.1 19h5.8c.549 0 1.428-.139 1.951-.307l1.196-.387c.524-.167.953-.757.953-1.306V9.199C17 8.646 16.352 8 15.8 8z"></path>
179+
</symbol>
180+
181+
<symbol viewBox="0 0 20 20" id="locked">
182+
<path d="M15.8 8H14V5.6C14 2.703 12.665 1 10 1 7.334 1 6 2.703 6 5.6V8H4c-.553 0-1 .646-1 1.199V17c0 .549.428 1.139.951 1.307l1.197.387C5.672 18.861 6.55 19 7.1 19h5.8c.549 0 1.428-.139 1.951-.307l1.196-.387c.524-.167.953-.757.953-1.306V9.199C17 8.646 16.352 8 15.8 8zM12 8H8V5.199C8 3.754 8.797 3 10 3c1.203 0 2 .754 2 2.199V8z"/>
183+
</symbol>
184+
185+
<symbol viewBox="0 0 20 20" id="close">
186+
<path d="M14.348 14.849c-.469.469-1.229.469-1.697 0L10 11.819l-2.651 3.029c-.469.469-1.229.469-1.697 0-.469-.469-.469-1.229 0-1.697l2.758-3.15-2.759-3.152c-.469-.469-.469-1.228 0-1.697.469-.469 1.228-.469 1.697 0L10 8.183l2.651-3.031c.469-.469 1.228-.469 1.697 0 .469.469.469 1.229 0 1.697l-2.758 3.152 2.758 3.15c.469.469.469 1.229 0 1.698z"/>
187+
</symbol>
188+
189+
<symbol viewBox="0 0 20 20" id="large-arrow">
190+
<path d="M13.25 10L6.109 2.58c-.268-.27-.268-.707 0-.979.268-.27.701-.27.969 0l7.83 7.908c.268.271.268.709 0 .979l-7.83 7.908c-.268.271-.701.27-.969 0-.268-.269-.268-.707 0-.979L13.25 10z"/>
191+
</symbol>
192+
193+
<symbol viewBox="0 0 20 20" id="large-arrow-down">
194+
<path d="M17.418 6.109c.272-.268.709-.268.979 0s.271.701 0 .969l-7.908 7.83c-.27.268-.707.268-.979 0l-7.908-7.83c-.27-.268-.27-.701 0-.969.271-.268.709-.268.979 0L10 13.25l7.418-7.141z"/>
195+
</symbol>
196+
197+
<symbol viewBox="0 0 24 24" id="jump-to">
198+
<path d="M19 7v4H5.83l3.58-3.59L8 6l-6 6 6 6 1.41-1.41L5.83 13H21V7z"/>
199+
</symbol>
200+
201+
<symbol viewBox="0 0 24 24" id="expand">
202+
<path d="M10 18h4v-2h-4v2zM3 6v2h18V6H3zm3 7h12v-2H6v2z"/>
203+
</symbol>
204+
205+
</defs>
206+
</svg>
207+
208+
<div id="swagger-ui"></div>
209+
210+
<script src="swagger-ui-bundle.js"></script>
211+
<script src="swagger-ui-standalone-preset.js"></script>
212+
<script>
213+
window.onload = function() {
214+
const ui = SwaggerUIBundle({
215+
url: "swagger/doc.json", // URL
216+
syntaxHighlight: true, // SyntaxHighlight
217+
dom_id: '#swagger-ui',
218+
validatorUrl: null,
219+
oauth2RedirectUrl: "", // Oauth2RedirectURL
220+
persistAuthorization: false, // PersistAuthorization
221+
presets: [SwaggerUIBundle.presets.apis, SwaggerUIStandalonePreset],
222+
plugins: [SwaggerUIBundle.plugins.DownloadUrl],
223+
layout: "StandaloneLayout",
224+
docExpansion: "none", // DocExpansion
225+
deepLinking: true, // DeepLinking
226+
defaultModelsExpandDepth: 1 // DefaultModelsExpandDepth
227+
});
228+
229+
const defaultClientId = ""; // Oauth2DefaultClientID
230+
if (defaultClientId) ui.initOAuth({ clientId: defaultClientId });
231+
232+
window.ui = ui;
233+
}
234+
</script>
235+
236+
</body>
237+
</html>
238+
```
239+
240+
The final project directory should have the following structure:
241+
242+
```sh
243+
project/
244+
├── main.go
245+
├── docs/ # generated by swag init
246+
│ ├── docs.go
247+
│ ├── swagger.json
248+
│ └── swagger.yaml
249+
├── swagger-ui/ # custom UI (copied from Swagger UI dist)
250+
│ ├── favicon-16x16.png
251+
│ ├── favicon-32x32.png
252+
│ ├── index.html
253+
│ ├── swagger-ui-bundle.js
254+
│ ├── swagger-ui-standalone-preset.js
255+
│ ├── swagger-ui.css
256+
│ └── ...other swagger ui dist files as needed...
257+
├── go.mod
258+
└── go.sum
259+
```
260+
261+
7. Serve static files
262+
263+
Add this line into `main.go`
264+
265+
```go
266+
h.GET("/swagger/*any", adaptor.HertzHandler(httpSwagger.WrapHandler))
267+
268+
// Add this line
269+
h.Static("/", "./swagger-ui")
270+
271+
h.Spin()
272+
273+
// Rest of code
274+
```
275+
276+
8. Run program
277+
278+
```sh
279+
go run main.go
280+
```
281+
282+
On a web browser, go to http://localhost:8888/index.html to see the customised Swagger UI.
283+
284+
## Legacy Documentation (Deprecated)
285+
9286
Hertz middleware to automatically generate RESTful API documentation with Swagger 2.0.
10287

11288
The implementation of the [swagger](https://github.com/hertz-contrib/swagger) extension refers to the implementation of [Gin](https://github.com/swaggo/gin-swagger).

0 commit comments

Comments
 (0)