• 为它加上Swagger
    • 安装 swag
      • 验证是否安装成功
    • 安装 gin-swagger
    • 初始化
    • 编写API注释
    • 生成
    • 验证
    • 参考
      • 本系列示例代码

    为它加上Swagger

    一个好的 API's，必然离不开一个好的API文档

    要开发纯手写 API 文档，不存在的 :=)

    项目地址：https://github.com/EDDYCJY/go-gin-example

    安装 swag

    1、go get

    1. $ go get -u github.com/swaggo/swag/cmd/swag

    若 $GOPATH/bin 没有加入$PATH中，你需要执行将其可执行文件移动到$GOBIN下

    1. mv $GOPATH/bin/swag /usr/local/go/bin

    2、gopm get

    该包有引用golang.org上的包，若无科学上网，你可以使用 gopm 进行安装

    1. gopm get -g -v github.com/swaggo/swag/cmd/swag
    3. cd $GOPATH/src/github.com/swaggo/swag/cmd/swag
    5. go install

    同理将其可执行文件移动到$GOBIN下

    验证是否安装成功

    1. $ swag -v
    2. swag version v1.1.1

    安装 gin-swagger

    1. $ go get -u github.com/swaggo/gin-swagger
    3. $ go get -u github.com/swaggo/gin-swagger/swaggerFiles

    注：三个包都有一定大小，安装需要等一会或要科学上网

    初始化

    编写API注释

    Swagger 中需要将相应的注释或注解编写到方法上，再利用生成器自动生成说明文件

    gin-swagger 给出的范例：

    1. // @Summary Add a new pet to the store
    2. // @Description get string by ID
    3. // @Accept  json
    4. // @Produce  json
    5. // @Param   some_id     path    int     true        "Some ID"
    6. // @Success 200 {string} string    "ok"
    7. // @Failure 400 {object} web.APIError "We need ID!!"
    8. // @Failure 404 {object} web.APIError "Can not find ID"
    9. // @Router /testapi/get-string-by-int/{some_id} [get]

    我们可以参照 Swagger 的注解规范和范例去编写

    1. // @Summary 新增文章标签
    2. // @Produce  json
    3. // @Param name query string true "Name"
    4. // @Param state query int false "State"
    5. // @Param created_by query int false "CreatedBy"
    6. // @Success 200 {string} json "{"code":200,"data":{},"msg":"ok"}"
    7. // @Router /api/v1/tags [post]
    8. func AddTag(c *gin.Context) {
    1. // @Summary 修改文章标签
    2. // @Produce  json
    3. // @Param id param int true "ID"
    4. // @Param name query string true "ID"
    5. // @Param state query int false "State"
    6. // @Param modified_by query string true "ModifiedBy"
    7. // @Success 200 {string} json "{"code":200,"data":{},"msg":"ok"}"
    8. // @Router /api/v1/tags/{id} [put]
    9. func EditTag(c *gin.Context) {

    参考的注解可见 gin-blog

    生成

    我们进入到gin-blog的项目根目录中，执行初始化命令

    1. [$ gin-blog]# swag init
    2. 2018/03/13 23:32:10 Generate swagger docs....
    3. 2018/03/13 23:32:10 Generate general API Info
    4. 2018/03/13 23:32:10 create docs.go at  docs/docs.go

    完毕后会在项目根目录下生成docs

    1. docs/
    2. ├── docs.go
    3. └── swagger
    4.     ├── swagger.json
    5.     └── swagger.yaml

    我们可以检查 docs.go 文件中的 doc 变量，详细记载中我们文件中所编写的注解和说明
    docs.go

    验证

    大功告成，访问一下 http://127.0.0.1:8000/swagger/index.html， 查看 API 文档生成是否正确

    swagger

    参考

    本系列示例代码

    • go-gin-example