swagger界面换装

golang语言警告，其他语言需要DIY哟

Swagger这么好的东西，可惜界面太难用，API一旦多起来，找起来特别吃力，有人肯定说，自己做一套？不，觉得难用的可能不止我一个，先搜索看看，经过3分钟努力，我发现了这个

来自Stack 复制/粘贴 flow

这个ReDoc看着不错，加入“购物车”。

看看对照效果

PetStore对比

左侧tag分类折叠，中部显示请求、返回数据结构和注释、右边显示URI和单纯的结构。

优缺点：
swagger-ui
结构紧凑，整体内容居中，带有接口测试客户端，在接口数量较少时阅读、测试方便。
ReDoc
tag分类默认折叠，方便找接口；中部展示结构注释，符合使用习惯；右侧纯结构方便构造请求参数；美中不足，缺少测试客户端。

嗯，挺符合我的使用习惯的，swagger-ui来做接口测试实在鸡肋，那么就接入试试吧。

以下内容，使用开源项目 gin-vue-admin
展示替换 swagger-ui 为 ReDoc 的方法

// 我们得实现个返回ReDoc的Handler
// 用它来替换掉这个swaggerFiles.Handler
Router.GET("/swagger/*any", ginSwagger.WrapHandler(swaggerFiles.Handler))

_{让我们一起康康 swaggerFiles.Handler}
_{WrapHandler 调用 CustomWrapHandler，并向它传递 "doc.json" 作为参数。}
_{CustomWrapHandler 函数最末尾就是核心啦，根据请求的URI，返回 index.html 或 doc.json 两个文件。}
那么，我们只要实现一个返回 ReDoc index.html 或 doc.json 的handler就OK啦。

我的实现如下

// 初始化总路由

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，要改为当前项目的
        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 href="https://fonts.googleapis.com/css?family=Montserrat:300,400,700|Roboto:300,400,700" 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最终效果

最终效果

最后编辑于：2020.09.06 21:53:05