Go Swagger 教程：如何使用 go-swagger 创建 Golang API 文档
作为一名开发人员，您可能了解记录和组织所有 API 的重要性，并且您也知道并非每个开发人员都喜欢这个文档部分。为此，我们需要一些可以轻松用于准备 API 文档的工具。好吧，第一个出现的工具是 Swagger。
什么是招摇？
Swagger 是一组用于编写基于 REST 的 API 的开源工具。它简化了编写 API 的过程，指定标准并提供编写和组织可扩展 API 所需的工具。
为什么要使用招摇？
如前所述，当我们必须遵循方法论时，文档是“必须的”。使用 swagger，我们可以通过在代码中添加注释来创建 API 文档。
现在问题可能会出现Swagger 只是用于 API 文档吗？不，这不对。
借助 Swagger，我们可以为任何技术（如 Node、AngularJS、PHP 等）生成客户端。因此，它有利于我们应用程序的命名约定、维护最佳实践和通用结构。此外，它确实节省了客户端的编码时间。
现在，让我们看看我们将在本教程中做什么。
准备好用创新技术彻底改变您的行业了吗？
联系像 Bacancy 这样经验丰富的Golang 开发公司来创建时尚、高性能的应用程序，让您的竞争对手望尘莫及。
教程目标：使用 Go Swagger 的 Golang API 文档
在本教程中，我们将使用Go swagger制作一个演示应用程序并准备 API 文档。观看下面的视频，了解我们将在本教程中构建的内容。
Go Swagger 示例：如何创建 Golang API 文档
事不宜迟，让我们开始编码部分。以下是创建 Golang API 文档的分步说明。
创建项目目录
使用以下命令创建项目目录。
mkdir goswaggerCD 飘飘然去 mod 初始化 goswagger
安装招摇
下载_url=$(curl -s https://api.github.com/repos/go-swagger/go-swagger/releases/latest | \
jq -r '.资产[] | 选择(.name | 包含("'"$(uname | tr '[:upper:]' '[:lower:]')"'_amd64")) | .browser_download_url')curl -o /usr/local/bin/swagger -L'#' "$download_url"chmod +x /usr/local/bin/swagger
下载依赖
接下来，我们将下载所需的依赖项
对于这个演示，我们将使用：
Mux：处理http请求和路由
命令：
去获取 github.com/gorilla/mux
Swagger：处理 swagger 文档
命令：
去获取 github.com/go-openapi/runtime/middleware
MySQL：处理 MySQL 查询
命令：
github.com/go-sql-driver/mysql去获取 github.com/jmoiron/sqlx
从根目录导入数据库 company.sql
在根目录下创建main.go。建立数据库连接、API 路由和 Swagger 文档。
r := mux.NewRouter()
dbsqlx := 配置.ConnectDBSqlx()
hsqlx := 控制器.NewBaseHandlerSqlx(dbsqlx)
公司 := r.PathPrefix("/admin/company").Subrouter()
company.HandleFunc("/", hsqlx.PostCompanySqlx).Methods("POST")
公司.HandleFunc("/", hsqlx.GetCompaniesSqlx).Methods("GET")
company.HandleFunc("/{id}", hsqlx.EditCompany).Methods("PUT")
company.HandleFunc("/{id}", hsqlx.DeleteCompany).Methods("DELETE")
使用 Go Swagger 编写文档
现在，让我们看看如何使用 Swagger 进行文档化。它将由基本配置、模型和 API 路由组成。
基本配置
// 公司 API://版本：0.0.1// 标题：Company Api// 方案：http, https// 主机：localhost:5000// 基本路径：/// 产生：// - 应用程序/json//// 安全定义：// 接口密钥：// 类型：apiKey// 在：标题// 名称：授权//招摇：元包控制器
对于安全定义，我们可以使用 API 密钥，它可以为每个 API 进行验证。
楷模
为我们的 API 的请求和响应创建模型。下面是一些带有 swagger 注释的结构示例。我们可以为每个字段添加名称、类型、模式、必需和描述。
类型 ReqAddCompany 结构 {
// 公司名称
// 输入：字符串
名称字符串 `json:"name"validate:"required,min=2,max=100,alpha_space"`
// 公司状况
// 输入：int64
Status int64 `json:"status" validate:"required"`}// swagger:parameters admin addCompany类型 ReqCompanyBody 结构 {
// - 名称：正文
// 在：主体
// 描述：名称和状态
// 模式：
// 类型：对象
// "$ref": "#/definitions/ReqAddCompany"
// 必需：真
正文 ReqAddCompany `json:"body"`}// swagger:模型公司类型公司结构{
//公司ID
// 输入：int64
ID int64 `json:"id"`
// 公司名称
// 输入：字符串
名称字符串 `json:"name"`
// 公司状况
// 输入：int64
状态 int64 `json:"status"`}// swagger:model CommonError类型 CommonError 结构 {
// 错误状态
// 输入：int64
状态 int64 `json:"status"`
// 错误信息
// 输入：字符串
消息字符串 `json:"message"`}
API路由
我们可以为每条路线添加 swagger 注释。如果需要，我们可以在其中指定请求和响应模型、路由名称、请求方法、描述和 API 密钥。
// swagger:route GET /admin/company/ admin listCompany// 获取公司列表//// 安全：// - api密钥：[]// 响应：// 401: 常见错误// 200: 获取公司func (h *BaseHandlerSqlx) GetCompaniesSqlx(w http.ResponseWriter, r *http.Request) {
响应：= GetCompanies{}
公司 := models.GetCompaniesSqlx(h.db)
响应.Status = 1
response.Message = lang.Get("成功")
response.Data = 公司
w.Header().Set("内容类型", "application/json")
json.NewEncoder(w).编码（响应）}
// swagger:route POST /admin/company/ admin addCompany//创建一个新公司//// 安全：// - api密钥：[]// 响应：// 401: 常见错误// 200: 获取公司func (h *BaseHandlerSqlx) PostCompanySqlx(w http.ResponseWriter, r *http.Request) {
w.Header().Set("内容类型", "application/json")
响应：=获取公司{}
解码器：= json.NewDecoder（r.Body）
var reqcompany *models.ReqCompany
错误 := decoder.Decode(&reqcompany)
fmt.Println(错误)
如果错误！=无{
json.NewEncoder(w).Encode(ErrHandler(lang.Get("invalid_request")))
返回
}
公司，errmessage := models.PostCompanySqlx(h.db, reqcompany)
如果错误消息！=“”{
json.NewEncoder(w).Encode(ErrHandler(错误消息))
返回
}
响应.Status = 1
response.Message = lang.Get("插入成功")
response.Data = 公司
json.NewEncoder(w).编码（响应）}
// swagger:route PUT /admin/company/{id} admin editCompany// 编辑公司//// 消费：// - 应用程序/x-www-form-urlencoded// 安全：// - api密钥：[]// 响应：// 401: 常见错误// 200: 获取公司func (h *BaseHandlerSqlx) EditCompany(w http.ResponseWriter, r *http.Request) {
r.ParseForm()
w.Header().Set("内容类型", "application/json")
变量 := mux.Vars(r)
响应：=获取公司{}
id, 错误 := strconv.ParseInt(vars["id"], 10, 64)
如果错误！=无{
json.NewEncoder(w).Encode(ErrHandler(lang.Get("invalid_request")))
返回
}
var reqcompany 模型.ReqCompany
reqcompany.Status, err = strconv.ParseInt(r.FormValue("状态"), 10, 64)
reqcompany.Name = r.FormValue("名称")
如果错误！=无{
json.NewEncoder(w).Encode(ErrHandler(lang.Get("invalid_request")))
返回
}
公司，errmessage := models.EditCompany(h.db, &reqcompany, id)
如果错误消息！=“”{
json.NewEncoder(w).Encode(ErrHandler(错误消息))
返回
}
响应.Status = 1
response.Message = lang.Get("更新成功")
response.Data = 公司
json.NewEncoder(w).编码（响应）}
// swagger:route DELETE /admin/company/{id} admin deleteCompany// 删除公司//// 安全：// - api密钥：[]// 响应：// 401: 常见错误// 200: 共同成功// 创建句柄删除获取公司func (h *BaseHandlerSqlx) DeleteCompany(w http.ResponseWriter, r *http.Request) {
变量 := mux.Vars(r)
errmessage := models.DeleteCompany(h.db, vars["id"])
如果错误消息！=“”{
json.NewEncoder(w).Encode(ErrHandler(错误消息))
返回
}
成功响应：= CommonSuccess{}
成功响应.Status = 1
successresponse.Message = lang.Get("delete_success")
w.Header().Set("内容类型", "application/json")
json.NewEncoder(w).Encode(成功响应)}
完成 api 后，我们可以在根目录中使用以下命令从 swagger 注释生成 swagger yaml或JSON文件。
swagger generate spec -o ./swagger.yaml –scan-models会在根目录下
生成一个swagger.yaml文件。我们也可以用同样的方式创建一个JSON文件。
使用这个文件，我们可以在main.go文件中添加文档的路由。
// 开发者文档
opts := middleware.SwaggerUIOpts{SpecURL: "/swagger.yaml"}
sh := middleware.SwaggerUI(opts, nil)
r.Handle("/文档", sh)
// 共享文档
// opts1 := middleware.RedocOpts{SpecURL: "/swagger.yaml"}
// sh1 := middleware.Redoc(opts1, nil)
// r.Handle("/docs", sh1)
完成这些步骤后，开发人员文档将类似于下图。
有关要与外部开发人员共享的只读 API，请参阅以下文档。
使用 Swagger 文档生成客户端
正如上面一开始提到的，Swagger 不仅仅用于 API 文档；它还用于 API 文档。我们还可以使用 Swagger 生成客户端。让我们看看下面的 AngularJS 客户端生成示例。
示例：AngularJS 的客户端生成。
npm 安装 ng-swagger-gen --save-devsudo node_modules/.bin/ng-swagger-gen -i ../swagger.yaml -o 后端/src/app
它将为要包含在 Swagger 文档中的所有 API 创建服务文件。同样，您可以为其他框架和技术生成客户端。
所以，这是关于使用 go-swagger 创建 Golang API 文档。如需完整文档，请随时访问 github 存储库：go-swagger-example
结论
我希望Go Swagger教程对您有所帮助，并消除了您对 Golang API 的 Swagger 文档的疑虑。如果您是 Golang 爱好者，请访问Golang 教程页面以获取更多此类教程并开始每天学习更多内容！如果您有任何问题，请随时发表评论并联系。
有时，许多需求需要熟练、知识渊博且敬业的开发人员来完成他们的 Golang 项目。对于此类要求，建议联系并聘请熟练的开发人员。您也在为您的项目寻找这样的开发人员吗？如果是，那为什么要浪费时间？立即联系 Bacancy 以聘请具有基础和高级 Golang 知识的Golang 开发人员。
还没有评论，来说两句吧...