基本介绍
GoFrame的Server默认自带的OpenAPI接口文档UI是redoc开源组件，该组件不支持页面Try It Out功能的。很多同学都在问，能否使用SwaggerUI页面来展示OpenAPI接口文档？有的企业内部并不支持连接外网的部分资源，那么能否将内部的接口文档UI替换为内部可访问的资源呢？
了解OpenAPI这个东东的小伙伴应该都知道，OpenAPI只是通用的接口定义规范，而展示的接口文档UI是可以随便替换的，并且这种UI界面以及平台还特别多！使用GoFrame Server来切换接口文档UI页面，或者将接口文档对接到第三方接口文档平台 - 非常简单！
使用示例
示例代码：https://github.com/gogf/gf/blob/master/example/httpserver/swagger-set-template/main.go
咱们通过代码来展示一下，如何快速地将接口文档UI切换为SwaggerUI。SwaggerUI的相关链接：
- https://github.com/swagger-api/swagger-ui
- https://github.com/swagger-api/swagger-ui/blob/master/docs/usage/installation.md
为了演示简便，这里将所有的代码都写到一个代码文件中，没有使用配置或页面文件。代码如下：main.go
| Code Block | ||
|---|---|---|
| ||
package main import ( "context" "fmt" "github.com/gogf/gf/v2/frame/g" "github.com/gogf/gf/v2/net/ghttp" ) // HelloReq hello request type HelloReq struct { g.Meta `path:"/hello" method:"get" sort:"1"` Name string `v:"required" dc:"Your name"` } // HelloRes hello response type HelloRes struct { Reply string `dc:"Reply content"` } // Hello Controller type Hello struct{} // Say function func (Hello) Say(ctx context.Context, req *HelloReq) (res *HelloRes, err error) { g.Log().Debugf(ctx, `receive say: %+v`, req) res = &HelloRes{ Reply: fmt.Sprintf(`Hi %s`, req.Name), } return } const ( swaggerUIPageContentMySwaggerUITemplate = ` <!DOCTYPE html> <html lang="en"> <head> <meta charset="utf-8" /> <meta name="viewport" content="width=device-width, initial-scale=1" /> <meta name="description" content="SwaggerUI"/> <title>SwaggerUI</title> <link rel="stylesheet" href="https://unpkgcdnjs.cloudflare.com/ajax/libs/swagger-ui-dist@latest/5.10.5/swagger-ui.min.css" /> </head> <body> <div id="swagger-ui"></div> <script src="https://unpkgcdnjs.cloudflare.com/ajax/libs/swagger-ui-dist@latest/5.10.5/swagger-ui-bundle.js" crossorigin></script> <script> window.onload = () => { window.ui = SwaggerUIBundle({ url: '/api.json{SwaggerUIDocUrl}', dom_id: '#swagger-ui', }); }; </script> </body> </html> ` ) type HelloReq struct { g.Meta `path:"/hello" method:"get"` Name string `v:"required" dc:"Your name"` } type HelloRes struct { Reply string `dc:"Reply content"` } type Hello struct{} func (Hello) Say(ctx context.Context, req *HelloReq) (res *HelloRes, err error) { g.Log().Debugf(ctx, `receive say: %+v`, req) res = &HelloRes{ Reply: fmt.Sprintf(`Hi %s`, req.Name), } return } func main() { s := g.Server() s.Use(ghttp.MiddlewareHandlerResponse) s.Group("/", func(group *ghttp.RouterGroup) { group.GET("/swagger", func(r *ghttp.Request) { r.Response.Write(swaggerUIPageContent) }) group.Bind( new(Hello), ) }) s.SetOpenApiPath("/api.json"SetSwaggerUITemplate(MySwaggerUITemplate) s.SetPort(8199) s.Run() }Run() } |
config.yaml
| Code Block | ||
|---|---|---|
| ||
server:
address: ":8199"
openapiPath: "/api.json"
swaggerPath: "/swagger" |
我们这里只定义了一个Hello的接口。可以看到，我们通过一个接口来展示SwaggerUI的HTML页面，并且将OpenAPI的接口文件路径定义为/api.json，没有启用Server自带的UI页面。执行后，终端输出：
| Code Block | ||
|---|---|---|
| ||
2022-05-18 20:41:09.160 [INFO] openapi specification is serving at address: http://127.0.0.1:8199/api.json 2022-05-18 20:41:09.161 [INFO] pid[57888]: http server started listening on [:8199] ADDRESS | METHOD | ROUTE | HANDLER | MIDDLEWARE ----------|--------|-----------|-----------------------------------------------------------------|-------------------- :8199 | ALL | /* | github.com/gogf/gf/v2/net/ghttp.internalMiddlewareServerTracing | GLOBAL MIDDLEWARE ----------|--------|-----------|-----------------------------------------------------------------|-------------------- :8199 | ALL | /api.json | github.com/gogf/gf/v2/net/ghttp.(*Server).openapiSpec | ----------|--------|-----------|-----------------------------------------------------------------|-------------------- :8199 | GET | /hello | main.(*Hello).Say | ----------|--------|-----------|-----------------------------------------------------------------|-------------------- :8199 | GET | /swagger | main.main.func1.1 | ----------|--------|-----------|-----------------------------------------------------------------|-------------------- |
戳此链接访问：http://127.0.0.1:8199/swagger/
页面展示如下：
开发者自定义其他的接口文档UI类似如此。
| title | 提示 |
|---|
常见UI模板
swagger-ui
| Code Block | ||
|---|---|---|
| ||
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="utf-8" />
<meta name="viewport" content="width=device-width, initial-scale=1" />
<meta name="description" content="SwaggerUI"/>
<title>SwaggerUI</title>
<link rel="stylesheet" href="https://cdnjs.cloudflare.com/ajax/libs/swagger-ui/5.10.5/swagger-ui.min.css" />
</head>
<body>
<div id="swagger-ui"></div>
<script src="https://cdnjs.cloudflare.com/ajax/libs/swagger-ui/5.10.5/swagger-ui-bundle.js" crossorigin></script>
<script>
window.onload = () => {
window.ui = SwaggerUIBundle({
url: '{SwaggerUIDocUrl}',
dom_id: '#swagger-ui',
});
};
</script>
</body>
</html> |
openapi-ui
| Code Block | ||
|---|---|---|
| ||
<!doctype html>
<html lang="en">
<head>
<meta charset="UTF-8" />
<title>openAPI UI</title>
</head>
<body>
<div id="openapi-ui-container" spec-url="{SwaggerUIDocUrl}" theme="light"></div>
<script src="https://cdn.jsdelivr.net/npm/openapi-ui-dist@latest/lib/openapi-ui.umd.js"></script>
</body>
</html> |
scalar-ui
| Code Block | ||
|---|---|---|
| ||
<!doctype html>
<html>
<head>
<title>Scalar API Reference</title>
<meta charset="utf-8" />
<meta
name="viewport"
content="width=device-width, initial-scale=1" />
</head>
<body>
<!-- Need a Custom Header? Check out this example https://codepen.io/scalarorg/pen/VwOXqam -->
<script
id="api-reference"
data-url="{SwaggerUIDocUrl}"></script>
<script src="https://cdn.jsdelivr.net/npm/@scalar/api-reference"></script>
</body>
</html> |
Github: https://github.com/scalar/scalar
| Panel | ||
|---|---|---|
| ||
|