使用 Gin-Docs 自动生成 API 文档

该插件移植自 Python 的 Flask-Docs,可以根据代码注释生成文档页面,支持离线文档下载和生成,支持在线调试,支持密码认证。

Gin-Docs

Gin API 文档自动生成插件

特性

  • 根据代码注释自动生成 Markdown 文档
  • 支持离线 Markdown 文档下载
  • 支持在线调试
  • 支持生成离线文档
    • HTML
    • Markdown

链接

https://github.com/kwkwc/gin-docs

安装

go get -u github.com/kwkwc/gin-docs

使用

go 复制代码
import (
    "github.com/gin-gonic/gin"
    gd "github.com/kwkwc/gin-docs"
)

r := gin.Default()
r.POST("/api/todo", AddTodo)
r.GET("/api/todo", GetTodo)

c := &gd.Config{}
apiDoc := gd.ApiDoc{Ge: r, Conf: c.Default()}
apiDoc.OnlineHtml()

r.Run()

查看文档页面

shell 复制代码
http://127.0.0.1/docs/api/

演示

在线演示

配置

go 复制代码
type Config struct {
	// 标题, default `API Doc`
	Title string
	// 版本, default `1.0.0`
	Version string
	// 描述
	Description string

	// 自定义 CDN CSS 模板
	CdnCssTemplate string
	// 自定义 CDN JS 模板
	CdnJsTemplate string

	// 自定义 url prefix, default `/docs/api`
	UrlPrefix string
	// 文档不存在时的描述, default `No documentation found for this API`
	NoDocText string
	// 启用文档页面, default `true`
	Enable bool
	// 使用 CDN, default `false`
	Cdn bool
	// 需要排除的 API 包名
	Exclude []string
	// 允许显示的方法, default `[]string{"GET", "POST", "PUT", "DELETE", "PATCH"}`
	MethodsList []string
	// SHA256 加密的授权密码,例如这里是 admin
	// echo -n admin | shasum -a 256
	// `8c6976e5b5410415bde908bd4dee15dfb167a9c873fc4bb8a81f6f2ab448a918`
	PasswordSha2 string
	// 启用 markdown 处理所有文档, default `true`
	AllMd bool
}

标记 @@@

shell 复制代码
# 默认以 markdown 处理所有文档
# 1. 如果希望指定处理,请使用 `@@@` 包裹
# 2. 如果希望展示原始文档,请关闭 `Config.AllMd`,并去除 `@@@` 标记

@@@
# 在这里写下你的 markdown 文档
@@@

API

go 复制代码
/*
Add todo

### args
|  args | required | location | type   |  help    |
|-------|----------|----------|--------|----------|
| name  |  true    |  json    | string | todo name |
| type  |  true    |  json    | string | todo type |

### request
```json
{"name": "xx", "type": "code"}
```

### response
```json
{"code": xxxx, "msg": "xxx", "data": null}
```
*/
func AddTodo(c *gin.Context) {
	c.JSON(http.StatusOK, gin.H{
		"todo": "post todo",
	})
}
go 复制代码
/*
Get todo

### description
> Get todo

### args
|  args | required | location |  type  |  help    |
|-------|----------|----------|--------|----------|
|  name |  true    |  query   | string | todo name |
|  type |  false   |  query   | string | todo type |

### request
```
http://127.0.0.1:8080/api/todo?name=xxx&type=code
```

### response
```json
{"code": xxxx, "msg": "xxx", "data": null}
```
*/
func GetTodo(c *gin.Context) {
	c.JSON(http.StatusOK, gin.H{
		"todo": "get todo",
	})
}


调试器

认证

生成离线文档

go 复制代码
r := gin.Default()

c := &gd.Config{}
apiDoc := gd.ApiDoc{Ge: r, Conf: c.Default()}

// HTML: 在 `htmldoc/` 生成离线 HTML 文档
out := "htmldoc"
apiDoc.OfflineHtml(out, true)

r.StaticFile(c.UrlPrefix+"/", filepath.Join(out, "index.html"))
r.StaticFile(c.UrlPrefix+"/data", filepath.Join(out, "data"))
r.Static(c.UrlPrefix+"/static", filepath.Join(out, "static"))

// Markdown: 生成 `doc.md` 离线 Markdown 文档
apiDoc.OfflineMarkdown("doc.md", true)

示例

Complete example

开发

bash 复制代码
# 克隆代码
git clone git@github.com:kwkwc/gin-docs.git

# 工作目录
cd gin-docs

# 安装依赖
make install

# 运行检查
make check-all

移植项目

Flask-Docs

相关推荐
里海_go17 小时前
Go 语言内存管理机制详解
go
斐波那契数列18 小时前
没有 JSX,也能在 Go 里写 React 风格 GUI:Tenon 的架构与性能实践
go
花椒技术18 小时前
花椒语音房联机五子棋:Go 服务端如何保证一回合只落一颗子
websocket·go
Sailing1 天前
🚀客户端都超时了,你的 Go 服务还在查库?Context 取消链路不打通,连接池迟早被打爆
后端·面试·go
2601_967980111 天前
欢迎来到Flask的世界
flask·文档·web应用·开发模式·api参考
小满zs2 天前
Go语言第二十一章(Gin上传文件)
后端·go
我不会起名字3222 天前
Agent 总调错工具?MCP 接进 Go 后端的 4 个约束
后端·go·agent·mcp
VIP_CQCRE3 天前
AI 音乐 API 上线后成本失控?用预算阈值、幂等任务和音频验收管住 Suno v6
python·api·suno·ai音乐·成本治理
用户298698530143 天前
在 Python 中把 Word 文档转换为 JSON 的三种实现方式
python·json·api
我不会起名字3224 天前
WebSocket 停机与在线状态:Shutdown 返回后还需要清理什么
redis·后端·websocket·go·即时通讯·im·故障排查