go-swagger简单使用

官网地址

/

安装go-swagger

go get -u /go-swagger/go-swagger/cmd/swagger
swagger version  

命令行工具
格式：swagger [OPTIONS] < command >。swagger -h查看 swagger 使用帮助

swagger generate spec -o 
swagger serve --no-open -F=swagger --port 36666 

-o：指定要输出的文件名。swagger 会根据文件名后缀.yaml 或者.json，决定生成的文件格式为 YAML 或 JSON。
–no-open：因为是在 Linux 服务器下执行命令，没有安装浏览器，所以使–no-open 禁止调用浏览器打开 URL。
-F：指定文档的风格，可选 swagger 和 redoc。我选用了 redoc，因为觉得 redoc 格式更加易读和清晰。
–port：指定启动的 HTTP 服务监听端口。

语法

注释语法	功能
swagger:mate	定义API接口全局基本信息
swagger:route	定义路由信息
swagger:operation	定义路由信息，可描述复杂的端点
swagger:parameters	定义API请求参数
swagger:response	定义API响应参数
swagger:model	定义可以复用的Go数据结构
swagger:allOf	嵌入其他Go结构体
swagger:strfmt	定义格式化的字符串
swagger:ignore	定义需要忽略的结构体

举例 docs

// Package docs name.   --name:服务名
//
// Documentation of  API.    --简述API服务
//
//     Schemes: http, https  
//     BasePath: /
//     Version: 0.1.0
//     Host: 127.0.0.1
//
//     Consumes:
//     - application/json
//
//     Produces:
//     - application/json
//
//    SecurityDefinitions:    --使用jwt
//    APIKey:
//      type: apiKey
//      name: Authorization
//      in: header
//
//     Security:
//     - APIKey: []
//
// swagger:meta
     package docs

举例 swagger:operation

// swagger:operation POST /v1/a/b a xxx  --a:相同的在一起
//
// 接口描述
//
// ---
// consumes:
// - multipart/form-data
// produces:
// - application/json
// parameters:
// - name: upload
//   in: formData
//   description: file field.
//   type: file
//   required: true
// responses:
//   '200':
//     description: hahahahah.
//     schema:
//       $ref: "#/definitions/successModel"
//   default:
//     description: error info.
//     schema:
//       $ref: "#/definitions/errorModel"

举例 swagger:route

// swagger:route POST /v1/login login loginRequest --loginReques:id,用来绑定请求内容
// 登录.
// responses:
//    200: loginRequest
//    default:errRequest

// swagger:parameters loginRequest	--loginRequest：上面说的绑定请求内容
type loginRequestWrapper struct {
	// in:body
	Body 
}

// swagger:response loginRequest
type getUserResponseWrapperLogin struct {
	// in:body
	Body 
}

// 这里可以写一些下面返回的描述
// swagger:response errRequest
type errResponseWrapperLogin struct {
	// in:body
	Body struct {
		// Error code.
		Code int `json:"code"`

		// Error message.
		Message string `json:"message"`
	}
}