在go标准库net/http搭建的Server中使用Swaggo自动生成Restful API文档

关于Swaggo

Swag将Go的注释转换为Swagger2.0文档。我们为流行的 Go Web Framework 创建了各种插件，这样可以与现有Go项目快速集成（使用Swagger UI）。

支持的Web框架

• gin
• echo
• buffalo
• net/http

快速开始

1. 将注释添加到API源代码中，请参阅声明性注释格式。

2. 使用如下命令下载swag：

go get -u github.com/swaggo/swag/cmd/swag
go get -u github.com/swaggo/http-swagger
go get -u github.com/alecthomas/template

前两个命令分别安装swag和http-swagger：

swag：该库将Go批注转换为Swagger 2.0文档（swagger.json / swagger.yaml），随后由http-swagger使用，以为Swagger UI提供服务。

http-swagger：该库使用swag生成的文档帮助提供Swagger UI

第三个命令是安装模板，这是Go的text/template包的分支。 swag生成的docs.go文件中需要此依赖关系，而在没有该依赖关系的情况下运行应用程序时，我们会看到一个错误。

3. 检查是否安装成功

$ swag -v
swag version v1.6.5

4. 在包含main.go文件的项目根目录运行swag init。这将会解析注释并生成需要的文件（docs文件夹和docs/docs.go）。

swag init

确保导入了生成的docs/docs.go文件，这样特定的配置文件才会被初始化。如果通用API指数没有写在main.go中，可以使用-g标识符来告知swag。

swag init -g http/api.go

生成Swagger文档

1.在代码中添加注释

我们首先通过注释我们的main方法来添加整个项目的一般描述。这些注解只不过是方法定义之前的注释，如下所示。

// @title RESTful API
// @version 1.0
// @description RESTful API 文档.
// @host localhost:8888
// @BasePath /
func main() {
   
   
	router := mux.NewRouter()
	router.PathPrefix("/swagger").Handler(httpSwagger.WrapHandler)
	http.ListenAndServe(":8888", router)
}

其中：

• titile: 文档标题
• version: 版本
• description,termsOfService,contact ... 这些都是一些声明，可不写。
• host,BasePath: 如果你想直接swagger调试API，这两项需要填写正确。前者为服务文档的端口，ip。后者为基础路径，像我这里就是“/api/v1”。
• 在原文档中还有securityDefinitions.basic,securityDefinitions.apikey等，这些都是用来做认证的，我这里暂不展开。

我希望这些注释是不言自明的。有关更多信息，可在swag github页面上找到所有可能的注释的详尽列表。

现在，我们已经添加了项目级别的文档，让我们向每个单独的API添加文档。

​ 首先自定义几个返回给前端的数据结构：SwaggerAccount、SwaggerAccounts、SwaggerIssue

type SwaggerAccount struct {
   
   
	ID string `json:"ID"`
	Company string