背景

作为一个后端开发，最不情愿的就是写接口文档和调试接口，可是与前端联调时又难免需要提供接口文档，要不然谁能理解你的奇思妙想呢。所幸，流传一些自动生成接口文档工具，解决了这方面的困扰，接下来看下swagger在golang中的应用

使用

安装swag工具

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

github地址：GitHub - swaggo/swag: Automatically generate RESTful API documentation with Swagger 2.0 for Go.

windows会在%GOBIN%/bin 下生成swag.exe(可使用go env查看GOBIN路径)

项目中引入与框架相适应的swagger客户端

比如echo框架：

go get -u github.com/swaggo/echo…

生成swagger json文件

在项目根目录下执行swag init 会默认在根目录下生成docs目录

如果main.go文件不在根目录下，可使用 -g 参数指定，详细参数可使用swag init --help查看。

后续注解有改动，再次执行该命令重新生成json文件
依赖外部文件使用--parseDependency
知道依赖外部文件的深度可以使用--parseDepth 指定深度，加快生成文件时间
例如：swag init -g cmd/main.go --parseDependency --parseDepth 1

代码中使用

main函数使用：

package main

import (
    "github.com/labstack/echo/v4"
    "github.com/swaggo/echo-swagger"

    _ "github.com/swaggo/echo-swagger/example/docs" //更换成项目中的docs目录，必须引入
)

// @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() {
    e := echo.New()
    //注册swagger路由
    e.GET("/swagger/*", echoSwagger.WrapHandler)

    e.Logger.Fatal(e.Start(":1323"))
}

HandleFunc使用注解：

// @Summary GetUser
// @Description 获取用户信息3
// @Accept  json
// @Param nick_name formData string true "昵称"
// @Param user_name formData string true "用户名称"
// @Param password formData string true "密码"
// @Param age formData int true "年龄"
// @Success 200 "获取信息成功"
// @Failure 400    "获取信息失败"
// @Router /getUser [get]
func (tagController) GetUser(ctx *pkgWeb.CustomContext) error {
    // User ID from path `users/:id`
    return ctx.String(http.StatusOK, "hello")
}

go-swagger注解：

// @Summary 摘要

// @Description 描述

// @Description 接口的详细描述

// @Id 全局标识符

// @Version 接口版本号

// @Tags 接口分组，相当于归类

// @Accept json 浏览器可处理数据类型

// @Produce json 设置返回数据的类型和编码

// @Param 参数格式 从左到右：参数名、入参类型、数据类型、是否必填和注释  例：id query int true "ID"

// @Success 响应成功 从左到右：状态码、参数类型、数据类型和注释  例：200 {string} string "success"

// @Failure 响应失败 从左到右：状态码、参数类型、数据类型和注释  例：400 {object}  string "缺少参数 ID"

// @Router 路由： 地址和http方法  例：/api/user/{id} [get]

// @contact.name 接口联系人

// @contact.url 联系人网址

// @contact.email 联系人邮箱

### 增加token验证方法

// @securityDefinitions.apikey ApiKeyAuth  安全方式

// @in header  token携带的位置，这里是在header中

// @name Authorization  heaer中的名称

注：暂时不支持泛型类型的返回数据类型，所以通用的返回数据模型可以使用
web.Result{data=model.Req} 这种形式指定具体的数据类型

浏览器查看页面

http://localhost:1323/swagger/index.html 换成你实际的ip和端口号

可以在页面中点击相应的接口直接调式接口

导入yapi

如果感觉swagger自带的界面不好看，可以将swagger json文件导入到yapi中

手动导入：

自动同步：

Swagger自动生成api文档

背景

使用