基本介绍

GoFrameServer默认自带的OpenAPI接口文档UI是[redoc](https://redocly.com/redoc/)开源组件,该组件不支持页面Try It Out功能的。很多同学都在问,能否使用SwaggerUI页面来展示OpenAPI接口文档?有的企业内部并不支持连接外网的部分资源,那么能否将内部的接口文档UI替换为内部可访问的资源呢?

了解OpenAPI这个东东的小伙伴应该都知道,OpenAPI只是通用的接口定义规范,而展示的接口文档UI是可以随便替换的,并且这种UI界面以及平台还特别多!使用GoFrame Server来切换接口文档UI页面,或者将接口文档对接到第三方接口文档平台 - 非常简单!

使用示例

咱们通过代码来展示一下,如果快速地将接口文档UI切换为SwaggerUISwaggerUI的相关链接:

为了演示简便,这里将所有的代码都写到一个代码文件中,没有使用配置或页面文件。代码如下:

  1. package main
  2. import (
  3. "context"
  4. "fmt"
  5. "github.com/gogf/gf/v2/frame/g"
  6. "github.com/gogf/gf/v2/net/ghttp"
  7. )
  8. const (
  9. swaggerUIPageContent = `
  10. <!DOCTYPE html>
  11. <html lang="en">
  12. <head>
  13. <meta charset="utf-8" />
  14. <meta name="viewport" content="width=device-width, initial-scale=1" />
  15. <meta name="description" content="SwaggerUI"/>
  16. <title>SwaggerUI</title>
  17. <link rel="stylesheet" href="https://unpkg.com/swagger-ui-dist@latest/swagger-ui.css" />
  18. </head>
  19. <body>
  20. <div id="swagger-ui"></div>
  21. <script src="https://unpkg.com/swagger-ui-dist@latest/swagger-ui-bundle.js" crossorigin></script>
  22. <script>
  23. window.onload = () => {
  24. window.ui = SwaggerUIBundle({
  25. url: '/api.json',
  26. dom_id: '#swagger-ui',
  27. });
  28. };
  29. </script>
  30. </body>
  31. </html>
  32. `
  33. )
  34. type HelloReq struct {
  35. g.Meta `path:"/hello" method:"get"`
  36. Name string `v:"required" dc:"Your name"`
  37. }
  38. type HelloRes struct {
  39. Reply string `dc:"Reply content"`
  40. }
  41. type Hello struct{}
  42. func (Hello) Say(ctx context.Context, req *HelloReq) (res *HelloRes, err error) {
  43. g.Log().Debugf(ctx, `receive say: %+v`, req)
  44. res = &HelloRes{
  45. Reply: fmt.Sprintf(`Hi %s`, req.Name),
  46. }
  47. return
  48. }
  49. func main() {
  50. s := g.Server()
  51. s.Group("/", func(group *ghttp.RouterGroup) {
  52. group.GET("/swagger", func(r *ghttp.Request) {
  53. r.Response.Write(swaggerUIPageContent)
  54. })
  55. group.Bind(
  56. new(Hello),
  57. )
  58. })
  59. s.SetOpenApiPath("/api.json")
  60. s.SetPort(8199)
  61. s.Run()
  62. }

我们这里只定义了一个Hello的接口。可以看到,我们通过一个接口来展示SwaggerUIHTML页面,并且将OpenAPI的接口文件路径定义为/api.json,没有启用Server自带的UI页面。执行后,终端输出:

  1. 2022-05-18 20:41:09.160 [INFO] openapi specification is serving at address: http://127.0.0.1:8199/api.json
  2. 2022-05-18 20:41:09.161 [INFO] pid[57888]: http server started listening on [:8199]
  3. ADDRESS | METHOD | ROUTE | HANDLER | MIDDLEWARE
  4. ----------|--------|-----------|-----------------------------------------------------------------|--------------------
  5. :8199 | ALL | /* | github.com/gogf/gf/v2/net/ghttp.internalMiddlewareServerTracing | GLOBAL MIDDLEWARE
  6. ----------|--------|-----------|-----------------------------------------------------------------|--------------------
  7. :8199 | ALL | /api.json | github.com/gogf/gf/v2/net/ghttp.(*Server).openapiSpec |
  8. ----------|--------|-----------|-----------------------------------------------------------------|--------------------
  9. :8199 | GET | /hello | main.(*Hello).Say |
  10. ----------|--------|-----------|-----------------------------------------------------------------|--------------------
  11. :8199 | GET | /swagger | main.main.func1.1 |
  12. ----------|--------|-----------|-----------------------------------------------------------------|--------------------

戳此链接访问:http://127.0.0.1:8199/swagger/

页面展示如下:

接口文档-自定义UI - 图1

开发者自定义其他的接口文档UI类似如此。