Skip to content

snow_doc

Jump to bottom
ACoderHIT edited this page Sep 8, 2019 · 3 revisions

简介

日常开发中，文档有着非常重要的地位，客户端和服务端的开发是通过先定义好接口格式，提供接口文档开始的。在项目交接中，接口文档也是让一个新人快速了解业务和代码的重要一环。然而在实际开发中，因为人的惰性和公司的人员变动会导致文档维护的不够完善。snow框架提供这样一个功能，正是为了让大家可以方便快捷的生成接口文档。

目录

app/http/controllers

为什么选择swagger

官方：Swagger是一个规范和完整的框架，用于生成、描述、调用和可视化 RESTful 风格的 Web 服务。总体目标是使客户端和文件系统作为服务器以同样的速度来更新。文件的方法，参数和模型紧密集成到服务器端的代码，允许API来始终保持同步。 我个人认为，swagger的一个优点是实时同步api与文档。另外一个优点在于方便测试和mock数据，在文档中，可以点击"Try it out" -> "Execute"来执行接口验证是否可用，同时也可以根据不同场景自己用多种数据进行边界测试。

如何运行

  • 使用前请先将snow框架升级 snow upgrade (v1.2.0后的version)
  • 再创建完项目后，执行snow doc
  • 然后对项目进行正常的编译和启动流程
  • 浏览器输入http://localhost:8080/swagger/index.html 即可看到文档

如何使用

目前接入的swagger是通过解析方法注释来生成文档，以test_validator接口为例（app/http/router.go文件中） ，在app/http/controllers/test.go文件中的HandleTestValidator方法上面加入注释

// validator的示例
// HandleTestValidator godoc
// @Summary HandleTestValidator的示例
// @Description HandleTestValidator的示例
// @Tags snow
// @Accept  json
// @Produce json
// @Param testValidator body entities.TestValidatorRequest true "example of validator"
// @Success 200 {array} entities.TestValidatorRequest
// @Failure 400 {object} controllers.HTTPError
// @Failure 404 {object} controllers.HTTPError
// @Failure 500 {object} controllers.HTTPError
// @Router /test_validator [post]

在TestValidatorRequest中每个字段加上example，比如：

type TestValidatorRequest struct {
	// tips，因为组件required不管是没传值或者传 0 or "" 都通过不了，但是如果用指针类型，那么0就是0，而nil无法通过校验
	Id   *int64  `json:"id" validate:"required" example:"1"`
	Age  int `json:"age" validate:"required,gte=0,lte=130" example:"20"`
	Name *string `json:"name" validate:"required" example:"snow"`
	Email string `json:"email" validate:"required,email" example:"snow@github.com"`
	Url  string `json:"url" validate:"required" example:"github.com/qit-team/snow"`
	Mobile string `json:"mobile" validate:"required" example:"snow"`
	RangeNum int `json:"range_num" validate:"max=10,min=1" example:"3"`
	TestNum *int `json:"test_num" validate:"required,oneof=5 7 9" example:"7"`
	Content *string `json:"content" example:"snow"`
	Addresses []*Address `json:"addresses" validate:"required,dive,required"`

}
//  Address houses a users address information
type Address struct {
	Street string `json:"street" validate:"required" example:"huandaodonglu"`
	City   string `json:"city" validate:"required" example:"xiamen"`
	Planet string `json:"planet" validate:"required" example:"snow"`
	Phone  string `json:"phone" validate:"required" example:"snow"`
}

解释一下几个关键注释的含义：

  • Param对参数的举例，如果"try it out"需要用到
  • Router为执行"try it out"时候的路径
  • Success和Failure 400等是对接口返回值的距离 注：举例中的success用的数据为entities.TestValidatorRequest，是因为这个接口入参出参形式一样，使用时建议分类request和response
  • 其他可以参考：https://github.com/swaggo/swag#general-api-info

tips

  • 如果注释更改，请重新执行snow doc，然后再编译运行
  • 如果项目端口更改，对应main.go函数上面的@host localhost:8080 注释请同步更改
Clone this wiki locally