安装与初始化
- 安装插件
go install github.com/swaggo/swag/cmd/swag@latest
- 安装依赖
go get -u github.com/swaggo/swag/cmd/swag
- 在包含main.go文件的项目根目录运行
swag init。这将会解析注释并生成需要的文件（docs文件夹和docs/docs.go）。
swag init
一定要在main.go的统计目录下，不然会出现如下错误：
切换到main.go统计目录后重新生成：
生成了一个docs目录
上述文件是根据swagger的注解生成的，虽然现在还没有swagger的注解，但是会生成默认的文件。
在项目开发时显然所有的api不可能写在一个go源文件中，就可以统一生成
swag init -g http/api.go
- 也可以使用fmt格式化swagger注解
swag fmt
基本命令
swag init -h
NAME:
swag init - Create docs.go
USAGE:
swag init [command options] [arguments...]
OPTIONS:
--generalInfo value, -g value API通用信息所在的go源文件路径，如果是相对路径则基于API解析目录 (默认: "main.go")
--dir value, -d value API解析目录 (默认: "./")
--exclude value 解析扫描时排除的目录，多个目录可用逗号分隔（默认：空）
--propertyStrategy value, -p value 结构体字段命名规则，三种：snakecase,camelcase,pascalcase (默认: "camelcase")
--output value, -o value 文件(swagger.json, swagger.yaml and doc.go)输出目录 (默认: "./docs")
--parseVendor 是否解析vendor目录里的go源文件，默认不
--parseDependency 是否解析依赖目录中的go源文件，默认不
--markdownFiles value, --md value 指定API的描述信息所使用的markdown文件所在的目录
--generatedTime 是否输出时间到输出文件docs.go的顶部，默认是
--codeExampleFiles value, --cef value 解析包含用于 x-codeSamples 扩展的代码示例文件的文件夹，默认禁用
--parseInternal 解析 internal 包中的go文件，默认禁用
--parseDepth value 依赖解析深度 (默认: 100)
--instanceName value 设置文档实例名 (默认: "swagger")
swag fmt -h
NAME:
swag fmt - format swag comments
USAGE:
swag fmt [command options] [arguments...]
OPTIONS:
--dir value, -d value API解析目录 (默认: "./")
--exclude value 解析扫描时排除的目录，多个目录可用逗号分隔（默认：空）
--generalInfo value, -g value API通用信息所在的go源文件路径，如果是相对路径则基于API解析目录 (默认: "main.go")
--help, -h show help (default: false)
swagger主键嵌入接口
swagger一般都是通过通过源码嵌入到接口上，用于生成接口的在线测试页面及api文档。
swago的常用注解，已注释的形式嵌入到go源码中，如下
// @Summary 接口简介：获取hello方法
// @Description 接口描述：这是一个没有入参，出参为hello信息的接口
// @Tags 测试
// @Accept json
// @Produce json
// @Param user_id path string true "用户ID" minlength(1) maxlength(100)
// @Success 200 {object} Response
// @Failure 400 {object} Response
// @Failure 404 {string} string "{"msg":"找不到路径了0.0"}"
// @Failure 500 {object} Response
// @Router /hello [get] --> 路由地址和请求方法
- @Summary，接口简介
- @Description，接口描述
- @Tags，接口的标签，用来给 API 分组的
- @Accept，接口接收入参的类型，支持mpfd（表单），json 等
- @Produce，接口返回的出参类型，支持mpfd（表单），json 等
- @Param，入参参数定义
- @Success，指定成功响应的数据，格式为 1.HTTP响应码 2.响应参数类型 3.响应数据类型 4.其它描述
- @Failure，失败响应后的数据，和 Success 一样
- @Router，指定路由和 HTTP 方法
原生net/http库使用swag
github地址https://github.com/swaggo/http-swagger
仅仅下载sawg只能生成api文档，不能生成在线文档并在线测试，因此还需要下载特定的依赖，用于整合web接口服务。
对于原生的net/httpswago官方提供了github.com/swaggo/http-swagger用于生成在线api文档。
- http=swagger下载依赖
go get -u github.com/swaggo/http-swagger
- 引入依赖
import "github.com/swaggo/http-swagger"
- 下载基于http接口注释生成在线api的依赖
go get github.com/swaggo/http-swagger/example/go-chi/docs
- 下载在线api测试服务器的依赖
go get github.com/go-chi/chi
使用整合swagger的httpSwagger编写api接口，并使用swagger注释，代码如下：
package main
import (
"net/http"
"github.com/go-chi/chi"
httpSwagger "github.com/swaggo/http-swagger"
_ "github.com/swaggo/http-swagger/example/go-chi/docs" // docs is generated by Swag CLI, you have to import it.
)
// @title Swagger Example API
// @version 1.0
// @description This is a sample server Petstore server.
// @termsOfService http://swagger.io/terms/
// @contact.name API Support
// @contact.url http://www.swagger.io/support
// @contact.email support@swagger.io
// @license.name Apache 2.0
// @license.url http://www.apache.org/licenses/LICENSE-2.0.html
// @host petstore.swagger.io
// @BasePath /v2
func main() {
r := chi.NewRouter()
r.Get("/swagger/*", httpSwagger.Handler(
httpSwagger.URL("http://localhost:1323/swagger/doc.json"), //The url pointing to API definition
))
http.ListenAndServe(":1323", r)
}
- 访问swagger在线api，任何sawgger结合的api接口在线了地址都是
http://ip:端口/swagger/index.html
swaggo支持若干很多web框架，具体请移步swag
