golang語言警告，其他語言需要DIY喲
Swagger這么好的東西，可惜界面太難用，API一旦多起來，找起來特別吃力，有人肯定說，自己做一套？不，覺得難用的可能不止我一個，先搜索看看，經(jīng)過3分鐘努力，我發(fā)現(xiàn)了這個
這個ReDoc看著不錯，加入“購物車”。
看看對照效果
左側(cè)tag分類折疊，中部顯示請求、返回數(shù)據(jù)結(jié)構(gòu)和注釋、右邊顯示URI和單純的結(jié)構(gòu)。
優(yōu)缺點：
swagger-ui
結(jié)構(gòu)緊湊，整體內(nèi)容居中，帶有接口測試客戶端，在接口數(shù)量較少時閱讀、測試方便。
ReDoc
tag分類默認(rèn)折疊，方便找接口；中部展示結(jié)構(gòu)注釋，符合使用習(xí)慣；右側(cè)純結(jié)構(gòu)方便構(gòu)造請求參數(shù)；美中不足，缺少測試客戶端。
嗯，挺符合我的使用習(xí)慣的，swagger-ui來做接口測試實在雞肋，那么就接入試試吧。
以下內(nèi)容，使用開源項目 gin-vue-admin
展示替換 swagger-ui 為 ReDoc 的方法
// 我們得實現(xiàn)個返回ReDoc的Handler
// 用它來替換掉這個swaggerFiles.Handler
Router.GET("/swagger/*any", ginSwagger.WrapHandler(swaggerFiles.Handler))
讓我們一起康康 swaggerFiles.Handler
WrapHandler 調(diào)用 CustomWrapHandler，并向它傳遞 "doc.json" 作為參數(shù)。
CustomWrapHandler 函數(shù)最末尾就是核心啦，根據(jù)請求的URI，返回 index.html 或 doc.json 兩個文件。
那么，我們只要實現(xiàn)一個返回 ReDoc index.html 或 doc.json 的handler就OK啦。
我的實現(xiàn)如下
// 初始化總路由
func Routers() *gin.Engine {
// ...
// 替換handler
// Router.GET("/swagger/*any", ginSwagger.WrapHandler(swaggerFiles.Handler))
Router.GET("/swagger/*any", handleReDoc)
// ...
}
func handleReDoc(ctx *gin.Context) {
i := strings.LastIndex(ctx.Request.URL.Path, "/")
if i == -1 {
return
}
suffix := ctx.Request.URL.Path[i+1:]
switch suffix {
case "doc.json":
// 載入swag生成的 docs/swagger.json
data, err := ioutil.ReadFile("docs/swagger.json")
if err != nil {
panic("cannot open docs/swagger.json")
}
_, _ = ctx.Writer.Write(data)
return
case "index.html":
// 這個index.html咱們得從ReDoc的github主頁上拿
// spec-url是swagger.json的URL，要改為當(dāng)前項目的
const redocIndexHTML = `<!DOCTYPE html>
<html>
<head>
<title>ReDoc換皮成功</title>
<!-- needed for adaptive design -->
<meta charset="utf-8"/>
<meta name="viewport" content="width=device-width, initial-scale=1">
<link rel="stylesheet">
<!--
ReDoc doesn't change outer page styles
-->
<style>
body {
margin: 0;
padding: 0;
}
</style>
</head>
<body>
<redoc spec-url='http://127.0.0.1:1888/swagger/doc.json'></redoc>
<script src="https://cdn.jsdelivr.net/npm/redoc@next/bundles/redoc.standalone.js"> </script>
</body>
</html>`
fmt.Println("ererer")
_, _ = ctx.Writer.Write([]byte(redocIndexHTML))
return
default:
_ = ctx.AbortWithError(http.StatusNotFound, errors.New("page not found"))
}
}
gin-vue-admin項目換上ReDoc最終效果
