建平台网站,lamp网站架构,织梦贷款网站源码,沈阳市城市建设网站文档一直是一项乏味的工作#xff08;以我个人的拙见#xff09;#xff0c;但也是编码过程中最重要的任务之一。在本文中#xff0c;我们将学习如何将Swagger规范与Gin框架集成。我们将实现JWT认证#xff0c;请求体作为表单数据和JSON。这里唯一的先决条件是Gin服务器。…文档一直是一项乏味的工作以我个人的拙见但也是编码过程中最重要的任务之一。在本文中我们将学习如何将Swagger规范与Gin框架集成。我们将实现JWT认证请求体作为表单数据和JSON。这里唯一的先决条件是Gin服务器。您可以在这里参考github上现有的api。
环境准备 下面是已存在项目的文件结构 后面我们在此基础上增加swagger生成API文档功能。
安装依赖
swag命令把Go 源码中的注释转换为Swagger文档。
go get -u github.com/swaggo/swag/cmd/swag另外还需要安装两个依赖
go get -u github.com/swaggo/gin-swagger
go get -u github.com/swaggo/filesgin-swagger使用gin中间件在Swagger 2.0中自动生成RESTful API文档文件生成swagger UI嵌入文件。
生成文档
在项目的根文件夹中运行swag init 命令根目录包含main.go文件。这将解析你的注释并生成所需的文件docs文件夹和docs/docs.go。 下面构建项目并启动web服务使用下面命令
$ go build 它将构建并创建可执行文件。然后运行可执行文件。现在导航到http://localhost:8081/swagger/index.html看看它是否正常工作。 好像有点不对劲。让我们一起努力吧。 导入生成的docs/docs在main.go的导入部门初始化特定配置。此外我们将在main.go中添加通用API注释。
package mainimport (_ go-api/docsgo-api/handlergithub.com/gin-gonic/ginswaggerFiles github.com/swaggo/filesginSwagger github.com/swaggo/gin-swagger
)// title Demo APIs
// version 1.0
// description Testing Swagger APIs.
// termsOfService http://swagger.io/terms/
// contact.name API Support
// contact.url http://www.swagger.io/support
// contact.email supportswagger.io
// securityDefinitions.apiKey JWT
// in header
// name token
// license.name Apache 2.0
// license.url http://www.apache.org/licenses/LICENSE-2.0.html
// host localhost:8081
// BasePath /api/v1
// schemes http
func main() {r : gin.Default()// url : ginSwagger.URL(http://localhost:8080/swagger/doc.json)r.GET(/swagger/*any, ginSwagger.WrapHandler(swaggerFiles.Handler))r.Run(:8080)
}请注意注释之间的间距因为这是swagger规范。此外每当我们添加或更新update注释时需要再次运行“swag init”命令来更新文档。好了现在让我们构建并运行它并检查我们是否取得了进展。 它起作用了。
另外请注意我们已经为UI中的JWT身份验证实现添加了下面的代码。
// securityDefinitions.apiKey JWT
// in header
// name tokenAPI文档注释
现在让我们将文档注释添加到API端点。
package handlerimport (github.com/gin-gonic/gin
)// Summary 获取item
// Description 根据ID查询item信息
// Accept json
// Produce json
// Param id path int true ID
// Success 200 {object} map[string]interface{}
// Router /items/{id} [get]
func GetItem(c *gin.Context) {// Implement the logic to get an item
}// Summary 示例 API
// Description 这是一个示例 API 的描述
// Accept mpfd
// Produce json
// Param item formData model.Item true item data
// Success 200 {object} map[string]interface{}
// Router /items/create [post]
func CreateItem(c *gin.Context) {// Implement the logic to create a new item
}我们使用Accept作为mpfd (multipart/form-data)它生成JSON并使用Item 模型作为DTO。Tags有助于将api组织到一个组中。你也可以使用swag fmt来格式化注释。
Item模型代码
package modeltype Item struct {ID int json:idName string json:name binding:requiredPrice float64 json:price binding:required
}
再次运行 swag init 命令 ,然后构建项目并运行 我们看到Item数据的必填属性与model定义一致。
最后一步给Post请求增加JWT 认证。我们在请求端点文档中增加下面代码
// securityDefinitions.apiKey token
// in header
// name Authorization
// Security JWT再次 运行可以看到右侧锁标志。
总结
本文介绍了Gin如何集成Swagger包括安装依赖增加API接口注释文档以及如何配置表单数据参数和JWT认证等。Gin愈学习愈快乐 Go!
