golang自动生成符合OpenAPI规范的RESTful API文档插件docs的使用

Golang自动生成符合OpenAPI规范的RESTful API文档插件docs的使用

概述

go-OAS Docs可以将结构化的OAS3(Swagger3)对象转换为Open API规范，并自动在选定的路由和端口上提供服务。它非常灵活和简单，基本上可以集成到任何框架或现有项目中。

快速开始

  1. 下载docs：
$ go get -u github.com/go-oas/docs
  1. 添加一行注释到您希望使用的处理程序上：
// @OAS handleCreateUser /users POST
// @OAS handleGetUser /users GET

  1. 声明所有需要的共享文档元素，或重用示例目录中已存在的元素。

  2. 声明每个路由的特定文档元素。

使用方法

示例代码

为获取用户信息的处理程序添加OAS标签：

package users

import "net/http"

// @OAS handleGetUser /users GET
func (s *service) handleGetUser() http.HandlerFunc {
	return func(w http.ResponseWriter, r *http.Request) {
	}
}

为该端点创建唯一的API文档函数：

package main

import "github.com/go-oas/docs"

func handleGetUserRoute(oasPathIndex int, oas *docs.OAS) {
	path := oas.GetPathByIndex(oasPathIndex)

	path.Summary = "Get a User"
	path.OperationID = "getUser"
	path.RequestBody = docs.RequestBody{}
	path.Responses = docs.Responses{
		getResponseOK(),
	}

	path.Tags = append(path.Tags, "pet")
}

创建函数后，只需使用AttachRoutes()将其注册解析：

package main

import (
	"github.com/go-oas/docs"
)

func main() {
	apiDoc := docs.New()
	apiDoc.AttachRoutes([]interface{}{
		handleGetUserRoute,
	})
}

运行示例

要运行示例并通过Swagger UI查看托管文档，执行以下命令：

$ go run ./examples/file_output/*.go
# 或者运行前在internal/dist/index.html中注释第38行并取消注释第40行：
$ go run ./examples/stream_output/*.go

然后导航到http://localhost:3005/docs/api/（如果您没有更改任何内容）。

路线图

功能(GH issues) 描述 版本
Validation 基于OAS3.0.3为所有结构添加验证 v1.1.0
CLI 添加CLI支持 - 使其对CLI友好 v1.2.0
Postman 通过PM API添加Postman支持 v1.3.0
ReDoc 添加ReDoc支持作为SwaggerUI的替代方案 v1.4.0
E2E Auto-generation 将Go测试转换为Cypress/Katalon套件(将模拟单元测试转换为e2e测试) v1.5.0

更多关于golang自动生成符合OpenAPI规范的RESTful API文档插件docs的使用的实战教程也可以访问 https://www.itying.com/category-94-b0.html

1 回复

更多关于golang自动生成符合OpenAPI规范的RESTful API文档插件docs的使用的实战系列教程也可以访问 https://www.itying.com/category-94-b0.html


使用Go自动生成OpenAPI规范的RESTful API文档

在Go语言中，我们可以使用多种工具来自动生成符合OpenAPI规范的RESTful API文档。最常用的工具包括：

  1. swaggo/swag - 最流行的Go OpenAPI文档生成器
  2. go-swagger/go-swagger - 功能强大的Swagger工具集
  3. deepmap/oapi-codegen - 从OpenAPI规范生成代码或反向生成

下面我将重点介绍最常用的swaggo/swag的使用方法。

swaggo/swag 使用指南

1. 安装

go install github.com/swaggo/swag/cmd/swag@latest

2. 基本用法

首先，在你的路由处理函数上添加注释：

// @Summary 创建新用户
// @Description 创建新用户账户
// @Tags users
// @Accept json
// @Produce json
// @Param user body User true "用户信息"
// @Success 200 {object} User
// @Failure 400 {object} ErrorResponse
// @Failure 500 {object} ErrorResponse
// @Router /users [post]
func CreateUser(c *gin.Context) {
    // 处理逻辑
}

3. 初始化文档

在main.go中添加：

package main

import (
    "github.com/gin-gonic/gin"
    _ "yourproject/docs" // 导入生成的docs包
    swaggerFiles "github.com/swaggo/files"
    ginSwagger "github.com/swaggo/gin-swagger"
)

// @title 用户管理API
// @version 1.0
// @description 这是一个用户管理系统的API文档
// @host localhost:8080
// @BasePath /api/v1
func main() {
    r := gin.Default()
    
    // 添加swagger路由
    url := ginSwagger.URL("http://localhost:8080/swagger/doc.json") // 文档json地址
    r.GET("/swagger/*any", ginSwagger.WrapHandler(swaggerFiles.Handler, url))
    
    r.Run(":8080")
}

4. 生成文档

运行以下命令生成文档：

swag init

这会在项目根目录下创建docs文件夹，包含生成的文档文件。

5. 查看文档

启动服务后，访问http://localhost:8080/swagger/index.html即可查看API文档。

高级用法

模型定义

// User 用户模型
type User struct {
    // 用户ID
    ID int `json:"id" example:"1"`
    // 用户名
    Name string `json:"name" example:"张三"`
    // 用户年龄
    Age int `json:"age" example:"20"`
}

安全定义

// @SecurityDefinitions.apikey ApiKeyAuth
// @in header
// @name Authorization
// @description 类型: Bearer token

// 然后在需要认证的路由上添加:
// @Security ApiKeyAuth

分组路由

// 用户组路由
userGroup := r.Group("/users")
{
    userGroup.GET("", GetUsers)
    userGroup.POST("", CreateUser)
    userGroup.GET("/:id", GetUser)
}

集成示例

完整示例代码结构：

project/
├── main.go
├── go.mod
├── go.sum
├── docs/
│   ├── docs.go
│   ├── swagger.json
│   └── swagger.yaml
└── handlers/
    └── user_handler.go

注意事项

  1. 确保注释格式正确，每个注释行以//开头
  2. 每次修改API后需要重新运行swag init
  3. 生产环境建议禁用Swagger UI或添加访问限制
  4. 可以使用--output参数指定文档输出目录
  5. 支持Markdown格式的描述文本

通过这种方式，你可以轻松地为Go项目生成符合OpenAPI规范的API文档，并保持文档与代码同步更新。

回到顶部