golang嵌入式OpenAPI/Swagger文档UI插件go-redocReDoc的使用

go-redoc

go-redoc 是一个使用 ReDoc 和 Go 1.16+ 的 embed 包实现的嵌入式 OpenAPI 文档 UI，支持以下框架的中间件实现：net/http、gin、fiber、echo 和 iris。

该模板基于 ReDoc 的 bundle 模板，HTML 中已经包含了脚本，不需要依赖 CDN。

注意：这个包不生成 openapi 规范文件。

使用方法

基本配置

import "github.com/mvrilo/go-redoc"

...

doc := redoc.Redoc{
    Title:       "Example API",          // 文档标题
    Description: "Example API Description", // 文档描述
    SpecFile:    "./openapi.json",       // OpenAPI 规范文件路径，也支持 "./openapi.yaml"
    SpecPath:    "/openapi.json",        // 规范文件的服务路径，也支持 "/openapi.yaml"
    DocsPath:    "/docs",                // 文档 UI 的访问路径
}

不同框架的使用示例

net/http

import (
	"net/http"
	"github.com/mvrilo/go-redoc"
)

...

http.ListenAndServe(address, doc.Handler())

gin

import (
	"github.com/gin-gonic/gin"
	"github.com/mvrilo/go-redoc"
	ginredoc "github.com/mvrilo/go-redoc/gin"
)

...

r := gin.New()
r.Use(ginredoc.New(doc))

echo

import (
	"github.com/labstack/echo/v4"
	"github.com/mvrilo/go-redoc"
	echoredoc "github.com/mvrilo/go-redoc/echo"
)

...

r := echo.New()
r.Use(echoredoc.New(doc))

fiber

import (
	"github.com/gofiber/fiber/v2"
	"github.com/mvrilo/go-redoc"
	fiberredoc "github.com/mvrilo/go-redoc/fiber"
)

...

r := fiber.New()
r.Use(fiberredoc.New(doc))

iris

import (
	"github.com/kataras/iris/v12"
	"github.com/mvrilo/go-redoc"
	irisdoc "github.com/mvrilo/go-redoc/iris"
)

...

app := iris.New()
app.Use(irisdoc.New(doc))

完整示例

下面是一个使用 gin 框架的完整示例：

package main

import (
	"github.com/gin-gonic/gin"
	"github.com/mvrilo/go-redoc"
	ginredoc "github.com/mvrilo/go-redoc/gin"
)

func main() {
	// 配置 redoc
	doc := redoc.Redoc{
		Title:       "Example API",
		Description: "Example API Description",
		SpecFile:    "./openapi.json",
		SpecPath:    "/openapi.json",
		DocsPath:    "/docs",
	}

	// 创建 gin 路由
	r := gin.New()
	
	// 使用 redoc 中间件
	r.Use(ginredoc.New(doc))
	
	// 添加其他路由
	r.GET("/api", func(c *gin.Context) {
		c.JSON(200, gin.H{"message": "Hello World"})
	})
	
	// 启动服务
	r.Run(":8080")
}

使用这个示例，你可以：

  1. 访问 /docs 查看 API 文档
  2. 访问 /openapi.json 获取 OpenAPI 规范文件
  3. 访问 /api 测试 API 端点

确保在项目根目录下有 openapi.json 文件，或者根据需要修改 SpecFile 路径。


更多关于golang嵌入式OpenAPI/Swagger文档UI插件go-redocReDoc的使用的实战教程也可以访问 https://www.itying.com/category-94-b0.html

1 回复

更多关于golang嵌入式OpenAPI/Swagger文档UI插件go-redocReDoc的使用的实战系列教程也可以访问 https://www.itying.com/category-94-b0.html


使用go-redoc嵌入ReDoc OpenAPI/Swagger文档UI

go-redoc是一个Golang库，用于在Go应用程序中轻松嵌入ReDoc OpenAPI/Swagger文档UI。ReDoc是一个流行的OpenAPI/Swagger文档渲染器，提供美观、响应式的文档界面。

安装go-redoc

首先安装go-redoc库：

go get github.com/go-redoc/redoc

基本使用示例

下面是一个基本的使用示例，展示如何在Gin框架中嵌入ReDoc：

package main

import (
	"github.com/gin-gonic/gin"
	"github.com/go-redoc/redoc"
)

func main() {
	r := gin.Default()

	// 定义OpenAPI/Swagger JSON内容
	// 这里可以是从文件加载或动态生成的
	swaggerJSON := `{
		"openapi": "3.0.0",
		"info": {
			"title": "示例API",
			"version": "1.0.0"
		},
		"paths": {
			"/api/v1/users": {
				"get": {
					"summary": "获取用户列表",
					"responses": {
						"200": {
							"description": "成功响应"
						}
					}
				}
			}
		}
	}`

	// 创建ReDoc处理器
	doc := redoc.Redoc{
		Title:       "API文档",
		Description: "示例API文档",
		SpecFile:    []byte(swaggerJSON),
		SpecPath:    "/openapi.json", // 可选的，如果不提供则直接使用SpecFile
		DocsPath:    "/docs",         // 文档UI路径
	}

	// 设置路由
	docHandler := doc.Handler()
	r.GET("/docs", gin.WrapH(docHandler))
	r.GET("/openapi.json", func(c *gin.Context) {
		c.Data(200, "application/json", []byte(swaggerJSON))
	})

	// 启动服务器
	r.Run(":8080")
}

高级配置

go-redoc提供了多种配置选项来自定义ReDoc界面：

doc := redoc.Redoc{
	Title:       "API文档",
	Description: "示例API文档",
	SpecFile:    []byte(swaggerJSON),
	SpecPath:    "/openapi.json",
	DocsPath:    "/docs",
	
	// 可选配置
	RedocOptions: &redoc.Options{
		DisableSearch:     false,  // 禁用搜索
		NoAutoAuth:        true,   // 禁用自动认证
		HideDownloadButton: false, // 隐藏下载按钮
		Theme: &redoc.Theme{
			Colors: &redoc.Colors{
				Primary: &redoc.Color{
					Main: "#6EC5FF",
				},
			},
			Typography: &redoc.Typography{
				FontFamily: "Roboto, sans-serif",
			},
		},
	},
}

从文件加载OpenAPI规范

更常见的做法是从文件加载OpenAPI规范：

package main

import (
	"io/ioutil"
	"log"

	"github.com/gin-gonic/gin"
	"github.com/go-redoc/redoc"
)

func main() {
	r := gin.Default()

	// 从文件加载OpenAPI规范
	swaggerJSON, err := ioutil.ReadFile("openapi.json")
	if err != nil {
		log.Fatal("无法加载OpenAPI规范文件: ", err)
	}

	doc := redoc.Redoc{
		Title:       "API文档",
		Description: "从文件加载的API文档",
		SpecFile:    swaggerJSON,
		DocsPath:    "/docs",
	}

	r.GET("/docs", gin.WrapH(doc.Handler()))
	r.GET("/openapi.json", func(c *gin.Context) {
		c.Data(200, "application/json", swaggerJSON)
	})

	r.Run(":8080")
}

与其他框架集成

go-redoc也可以与其他Web框架集成，例如Echo：

package main

import (
	"github.com/labstack/echo/v4"
	"github.com/go-redoc/redoc"
)

func main() {
	e := echo.New()

	swaggerJSON := `{"openapi":"3.0.0","info":{"title":"Echo API","version":"1.0.0"}}`

	doc := redoc.Redoc{
		Title:    "Echo API文档",
		SpecFile: []byte(swaggerJSON),
		DocsPath: "/docs",
	}

	e.GET("/docs", echo.WrapHandler(doc.Handler()))
	e.GET("/openapi.json", func(c echo.Context) error {
		return c.Blob(200, "application/json", []byte(swaggerJSON))
	})

	e.Start(":8080")
}

自定义HTML模板

如果需要完全自定义HTML模板，可以覆盖默认模板：

doc := redoc.Redoc{
	Title:       "自定义模板API文档",
	SpecFile:    []byte(swaggerJSON),
	DocsPath:    "/docs",
	HTMLTemplate: `<!DOCTYPE html>
<html>
<head>
    <title>{{ .Title }}</title>
    <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">
    <style>
        body { margin: 0; padding: 0; }
    </style>
</head>
<body>
    <redoc spec-url='{{ .SpecURL }}'></redoc>
    <script src="https://cdn.jsdelivr.net/npm/redoc@next/bundles/redoc.standalone.js"></script>
</body>
</html>`,
}

总结

go-redoc提供了简单的方法在Go应用程序中嵌入ReDoc UI，主要特点包括：

  1. 支持从内存或文件加载OpenAPI规范
  2. 可自定义UI主题和选项
  3. 支持多种Web框架
  4. 允许完全自定义HTML模板

通过这种方式，你可以轻松地为你的Go API提供美观、交互式的文档界面，而无需额外的文档服务器。

回到顶部