beego+swagger生成API文档

# beego+swagger生成API文档

[TOC]

## 创建beego项目

```powershell
> bee new test
```

## 编写Controller描述

* Controller上的注释用来描述该Controller的用处：

```powershell
// Operations about User
type UserController struct {
	beego.Controller
}
```

![title](/api/file/getImage?fileId=6201388bc73b33aaff4d9c3f)

## 编写接口信息

* 对GET/POST/PUT/DELETE接口的描述写在相应方法的上方：

```
// @Title Create user
// @Description Create a user
// @Param body body models.User true "body for user info"
// @Success 200 {int} models.User.Id
// @Failure 403 body id empty
// @router / [POST]
func (u *UserController) Post() {
	var user models.User
	json.Unmarshal(u.Ctx.Input.RequestBody, &user)
	uid := models.AddUser(user)
	u.Data["json"] = map[string]string{"uid": uid}
	u.ServeJSON()
}
```

![title](/api/file/getImage?fileId=6201386fc73b33aaff4d9c3e)

## models中定义的外部可访问的结构会自动显示在文档中

![title](/api/file/getImage?fileId=620138c1c73b33aaff4d9c40)

## 在路由设置文件中编写API描述

* API的描述在routers/router.go的文件开始处定义：

```powershell
// @APIVersion 1.0.0
// @Title beego Test API
// @Description beego has a cool tool to autogenerate documents for your APIs
// @Contact 2687538884@qq.com
// @TermsOfServiceUrl http://localhost:8080/
// @License Apache 2.0
// @LicenseUrl http://www.apache.org/licenses/LICENSE-2.0.html
package routers

import (
	"relaxserver/controllers"

"github.com/astaxie/beego"
)

func init() {
	ns := beego.NewNamespace("/v1",
		beego.NSNamespace("/user",
			beego.NSInclude(
				&controllers.UserController{},
			),
		),
	)
	beego.AddNamespace(ns)
}
```

![title](/api/file/getImage?fileId=62013852c73b33aaff4d9c3d)

## beego启动时更新文档

```powershell
> bee run -gendoc=true -downdoc=true
```

## 浏览器中查看文档

* 浏览器中输入`localhost:8080/swagger`查看文档：

![title](/api/file/getImage?fileId=62013729c73b33aaff4d9c3c)

Starguard

导航

最近发表

友情链接