Swagger

blog.csdn.net/joychenweny…

项目地址

gin-swagger地址

安装

1、下载swag

github.com/swaggo/swag/cmd/swag 是一个 Go 语言的命令行工具，它通过解析 Go 语言源代码中的注释信息，用于自动生成 Swagger 文档。

go get -u github.com/swaggo/swag/cmd/swag

//新版本建议使用下面命令
go install github.com/swaggo/swag/cmd/swag@latest

go get -u github.com/swaggo/swag/cmd/swag 和 go install github.com/swaggo/swag/cmd/swag@latest 命令的区别在于：

• go get -u github.com/swaggo/swag/cmd/swag 命令会下载 swag 工具，并将其安装到 $GOPATH/bin 目录中，如果已经存在该工具，则会更新到最新版本。
• go install github.com/swaggo/swag/cmd/swag@latest 命令会安装 swag 工具的最新版本到 $GOPATH/bin 目录中，如果已经存在该工具，则会覆盖旧版本。

所以，如果你想下载 swag 工具并安装到 $GOPATH/bin 目录中，并希望自动更新到最新版本，可以使用 go get -u github.com/swaggo/swag/cmd/swag 命令。

如果你想安装 swag 工具的最新版本到 $GOPATH/bin 目录中，并覆盖旧版本，可以使用 go install github.com/swaggo/swag/cmd/swag@latest 命令。

2、初始化

swag init 命令可以根据 Go 代码中的注释自动生成 Swagger 文档。它会扫描指定的 Go 代码目录，并解析其中的注释，生成 Swagger 文档所需的 JSON 文件和 Markdown 文件。

swag init

3、下载gin-swagger

github.com/swaggo/gin-swagger 和 github.com/swaggo/files 是 Swag 工具的两个 Go 语言实现的中间件。

gin-swagger 是 Swag 工具的 Gin 中间件实现，它可以将 Swagger 文档和 Swagger UI 集成到 Gin 框架中，方便开发者在浏览器中查看和测试 API 接口。

files 是 Swag 工具的文件处理中间件实现，它可以将 Swag 自动生成的 Swagger 文档和 Swagger UI 界面静态文件打包到可执行文件中，方便程序部署和分发。同时，它还支持在程序运行时动态生成 Swagger 文档和 Swagger UI 界面，方便开发者进行调试和测试。

go get -u github.com/swaggo/gin-swagger
go get -u github.com/swaggo/files

导入

import "github.com/swaggo/gin-swagger" // gin-swagger middleware
import "github.com/swaggo/files" // swagger embed files
import docs "go-gin-demo/docs"//代表生成的docs.go路径，go-gin-demo是go.mod中的模块名称

4、在main.go中编写代码

package main

import (
	docs "go-gin-demo/docs"
	"net/http"
	"github.com/gin-gonic/gin"
	swaggerfiles "github.com/swaggo/files"
	ginSwagger "github.com/swaggo/gin-swagger"
)

// @BasePath /api/v1 所有的 API 接口的 URL 前缀都是 /api/v1。

// PingExample godoc
// @Summary ping example 接口的简短描述，用于在 Swagger 文档中显示。
// @Schemes 指定接口支持的协议，如 http、https 等。如果未指定，则默认为 http。
// @Description do ping 接口的详细描述，用于在 Swagger 文档中显示。
// @Tags example 接口所属的标签，用于在 Swagger 文档中对接口进行分类。
// @Accept json 接口支持的请求格式，如 json、xml 等。
// @Produce json 接口支持的响应格式，如 json、xml 等。
// @Success 200 {string} Helloworld 接口成功响应的状态码和响应格式，200 表示成功，{string} 表示响应格式为字符串，Helloworld 表示响应内容为 Helloworld。
// @Router /example/helloworld [get]  接口的路由信息，包括请求方法、URL 路径等。
func Helloworld(g *gin.Context) {
	g.JSON(http.StatusOK, "helloworld")
}

func main() {
	r := gin.Default()
	docs.SwaggerInfo.BasePath = "/api/v1"
	v1 := r.Group("/api/v1")
	{
		eg := v1.Group("/example")
		{
			eg.GET("/helloworld", Helloworld)
		}
	}
	r.GET("/swagger/*any", ginSwagger.WrapHandler(swaggerfiles.Handler))
	r.Run(":8084")

}

5、运行项目

go run main.go

查看swagger文档

http://localhost:8084/swagger/index.html

解决识别不了swag命令

验证安装成功，输入swag version，不报错即可。

blog.csdn.net/weixin_4550…

1、cd C:\Users\18222\go\pkg\mod\github.com\swaggo\swag@v1.16.1\cmd\swag

2、执行 go install

3、cd C:\Users\18222\go\bin

这个路径下有可执行文件，将此路径保存到环境变量

一定要在go代码中添加注释

一定要在go代码中添加注释，否则swagger无法识别

添加注释后执行swag init重新生成文档

然后不需要运行项目也能看到生成的文档结果

swag介绍

swag init 命令是一个用于生成 Swagger 文档的工具。Swagger 是一种用于描述 RESTful API 的规范，它提供了一种标准的方式来描述 API 的请求和响应格式、参数、错误等信息，可以帮助开发人员更好地理解和使用 API。

swag init 命令可以根据 Go 代码中的注释自动生成 Swagger 文档。它会扫描指定的 Go 代码目录，并解析其中的注释，生成 Swagger 文档所需的 JSON 文件和 Markdown 文件。

使用 swag init 命令的步骤如下：

1. 安装 swag 工具。在命令行中使用以下命令安装 swag 工具：

go get -u github.com/swaggo/swag/cmd/swag

2. 在 Go 代码中添加 Swagger 注释。在 Go 代码中使用以下格式的注释来描述 API 接口：

// @Summary 接口摘要
// @Description 接口详细描述
// @Tags 接口标签
// @Accept json
// @Produce json
// @Param paramName paramType dataType paramIn format description
// @Success statusCode {dataType} responseDescription
// @Failure statusCode {dataType} responseDescription
// @Router /path [httpMethod]
func handlerFunc(w http.ResponseWriter, r *http.Request) {
    // ...
}

其中，各个注释字段的含义如下：

• • @Summary：接口摘要，用于描述接口的简要功能。
  • @Description：接口详细描述，用于描述接口的详细功能、输入输出参数等信息。
  • @Tags：接口标签，用于将接口归类到一个或多个标签中。
  • @Accept：请求头部中 Accept 参数的值。
  • @Produce：响应头部中 Content-Type 参数的值。
  • @Param：请求参数的描述，包括参数名称、类型、位置、格式和描述等信息。
  • @Success：成功响应的描述，包括响应状态码、数据类型和描述等信息。
  • @Failure：失败响应的描述，包括响应状态码、数据类型和描述等信息。
  • @Router：路由信息，包括请求路径和请求方法。

3. 运行 swag init 命令。在命令行中使用以下命令运行 swag init 命令：

swag init

该命令会扫描当前目录下的所有 Go 文件，并解析其中的 Swagger 注释，生成 Swagger 文档所需的 JSON 文件和 Markdown 文件。

4. 查看生成的 Swagger 文档。生成的 Swagger 文档会保存在 docs 目录下的 swagger.json 和 swagger.yaml 文件中，以及 docs 目录下的 Markdown 文件中。您可以使用 Swagger UI 工具或其他 Swagger 客户端工具来查看和测试生成的 Swagger 文档。

@BasePath

@BasePath 是 Swagger 中的注释之一，用于指定 API 的基础路径。该注释可以用于 Go 语言编写的 API 代码中，通过解析注释，自动生成 Swagger 文档。

使用 @BasePath 注释可以指定 API 的基础路径，例如：

// @BasePath /api/v1

这表示该 API 的所有路由都是基于 /api/v1 进行的，比如 /api/v1/users、/api/v1/orders 等。

在 Swagger 文档中，基础路径会被用于生成请求的 URL，因此在使用 Swagger UI 调试 API 时，需要确保基础路径和实际的 API 地址一致。

@Summary

@Summary 是 Swagger 中的注释之一，用于指定 API 的简短描述。该注释可以用于 Go 语言编写的 API 代码中，通过解析注释，自动生成 Swagger 文档。

使用 @Summary 注释可以为 API 添加简短的描述，例如：

// @Summary 获取用户信息

这表示该 API 的作用是获取用户信息。

在 Swagger 文档中，@Summary 会被用于显示 API 的标题。

@Description

@Description 是 Swagger 中的注释之一，用于指定 API 的详细描述。该注释可以用于 Go 语言编写的 API 代码中，通过解析注释，自动生成 Swagger 文档。

使用 @Description 注释可以为 API 添加详细的描述，例如：

// @Description 根据用户 ID 获取用户信息

这表示该 API 的作用是根据用户 ID 获取用户信息。

在 Swagger 文档中，@Description 会被用于显示 API 的详细描述。

@Tags

@Tags 是 Swagger 中的注释之一，用于指定 API 所属的标签。该注释可以用于 Go 语言编写的 API 代码中，通过解析注释，自动生成 Swagger 文档。

使用 @Tags 注释可以为 API 添加标签，例如：

// @Tags 用户信息

这表示该 API 属于“用户信息”这个标签。

在 Swagger 文档中，@Tags 会被用于对 API 进行分类。

@Accept

@Accept 是 Swagger 中的注释之一，用于指定 API 支持的请求格式。该注释可以用于 Go 语言编写的 API 代码中，通过解析注释，自动生成 Swagger 文档。

使用 @Accept 注释可以指定 API 支持的请求格式，例如：

// @Accept json

这表示该 API 支持的请求格式为 JSON。

在 Swagger 文档中，@Accept 会被用于显示 API 支持的请求格式。

@Produce

@Produce 是 Swagger 中的注释之一，用于指定 API 支持的响应格式。该注释可以用于 Go 语言编写的 API 代码中，通过解析注释，自动生成 Swagger 文档。

使用 @Produce 注释可以指定 API 支持的响应格式，例如：

// @Produce json

这表示该 API 支持的响应格式为 JSON。

在 Swagger 文档中，@Produce 会被用于显示 API 支持的响应格式。

@Success

@Success 是 Swagger 中的注释之一，用于指定 API 成功响应的状态码和响应格式。该注释可以用于 Go 语言编写的 API 代码中，通过解析注释，自动生成 Swagger 文档。

使用 @Success 注释可以指定 API 成功响应的状态码和响应格式，例如：

// @Success 200 {string} OK

这表示该 API 成功响应时的状态码为 200，响应格式为字符串，响应内容为“OK”。

在 Swagger 文档中，@Success 会被用于显示 API 成功响应的状态码和响应格式。

@Router

@Router 是 Swagger 中的注释之一，用于指定 API 的路由信息。该注释可以用于 Go 语言编写的 API 代码中，通过解析注释，自动生成 Swagger 文档。

使用 @Router 注释可以指定 API 的路由信息，例如：

// @Router /api/v1/users/{id} [get]

这表示该 API 的路由为 /api/v1/users/{id}，请求方法为 GET。

在 Swagger 文档中，@Router 会被用于生成请求的 URL 和请求方法。

@Param

file formData file true "Voice file to upload"中

file代表参数名称，第二个file代表参数类型

true代表参数必填

// @Param file formData file true "Voice file to upload"
// @Param format formData string true "File format, e.g., 'mp3'"

// @Param props body map[string]interface{} true "Additional properties for voice conversion"

OptionFunc类型

OptionFunc类型来自于"go-swagger/swag/swagger"包。这个包提供了一些用于生成Swagger文档的工具。

OptionFunc类型是一个函数类型，它接受一个*SwaggerUIOpts类型的参数，并返回一个函数类型。它用于配置Swagger UI的选项，如URL路径、OAuth2验证等。以下是一个OptionFunc类型的示例：

type OptionFunc func(*SwaggerUIOpts) func()

这是一个比较常见的OptionFunc类型的定义，它接受一个*SwaggerUIOpts类型的参数，并返回一个函数类型。该函数类型用于配置Swagger UI的选项。例如，下面是一个使用OptionFunc类型的示例：

import (
    "github.com/swaggo/gin-swagger"
    "github.com/swaggo/gin-swagger/swaggerFiles"
)

r := gin.New()
r.GET("/swagger/*any", ginSwagger.WrapHandler(swaggerFiles.Handler, ginSwagger.URL("http://localhost:8080/swagger/doc.json"), ginSwagger.OptionFunc(func(opts *ginSwagger.SwaggerUIOpts) {
    opts.ConfigURL = "/swagger/doc.json"
})))

在上面的示例中，OptionFunc函数用于配置Swagger UI的选项。在这种情况下，它设置了Swagger UI的配置URL。

gin-swagger

WrapHandler

func WrapHandler(handler http.Handler, opts ...OptionFunc) gin.HandlerFunc

将Swagger UI的处理程序包装为Gin的处理程序。它需要一个http.Handler类型的参数，表示Swagger UI的处理程序，以及一个或多个OptionFunc类型的可选参数，用于配置Swagger UI的URL路径、OAuth2验证等。使用示例：

r := gin.New()
//ginSwagger.URL返回的是一个ginSwagger.URL，所以可以作为WrapHandler的参数
//ginSwagger.WrapHandler返回的是gin.HandlerFunc，所以可以作为Get的参数
r.GET("/swagger/*any", ginSwagger.WrapHandler(swaggerFiles.Handler, ginSwagger.URL("http://localhost:8080/swagger/doc.json")))

URL

func URL(url string) OptionFunc

设置Swagger UI的URL路径。它需要一个字符串类型的参数，表示Swagger UI的URL路径。使用示例：

r := gin.New()
r.GET("/swagger/*any", ginSwagger.WrapHandler(swaggerFiles.Handler, ginSwagger.URL("http://localhost:8080/swagger/doc.json")))

Files

func Files(dir http.FileSystem) OptionFunc

将Swagger UI文件提供给Gin。它需要一个http.FileSystem类型的参数，表示Swagger UI文件所在的文件系统。使用示例：

r := gin.New()
r.GET("/swagger/*any", ginSwagger.WrapHandler(swaggerFiles.Handler, ginSwagger.Files(myFileSystem)))

OAuth2

func OAuth2(clientID, clientSecret, realm string) OptionFunc

启用OAuth2验证。它需要三个字符串类型的参数，分别表示OAuth2客户端ID、客户端密钥和验证领域。使用示例：

r := gin.New()
r.GET("/swagger/*any", ginSwagger.WrapHandler(swaggerFiles.Handler, ginSwagger.OAuth2("my-client-id", "my-client-secret", "my-realm")))

OptionFunc

func OptionFunc(f func(opts *SwaggerUIOpts)) ginSwaggerOption

该方法返回一个ginSwaggerOption类型的值，它可以用于配置Swagger UI的选项。

OptionFunc方法接受一个函数类型的参数，该函数类型接受一个*SwaggerUIOpts类型的参数，并用于配置Swagger UI的选项。在函数体内，可以使用opts参数来设置Swagger UI的选项。例如，可以设置Swagger UI的配置URL、OAuth2验证等。

import (
    "github.com/swaggo/gin-swagger"
    "github.com/swaggo/gin-swagger/swaggerFiles"
)

r := gin.New()
r.GET("/swagger/*any", ginSwagger.WrapHandler(swaggerFiles.Handler, ginSwagger.URL("http://localhost:8080/swagger/doc.json"), ginSwagger.OptionFunc(func(opts *ginSwagger.SwaggerUIOpts) {
    opts.DocExpansion = "none"
})))

在上面的示例中，OptionFunc方法用于配置Swagger UI的选项。在这种情况下，它设置了Swagger UI的文档扩展选项，将其设置为"none"。这将禁用Swagger UI的文档扩展功能，使其只显示最基本的API信息。