Beego Automation Documentation (latest version)

This is a creation in Article, where the information may have evolved or changed.

Previously wrote an article using the Beego Automation API documentation: Beego Automation documentation, with the update of Beego, the method of Beego automation documents after 1.7.0 has also been updated, the most significant update is removed docs.go , used swagger.json , More in line with the characteristics of swagger. This article is an amendment and supplement to the previous article.

Environmental requirements

To install the latest go locale, install go to refer to Golang's environment configuration on Mac OS and to install the latest Beego framework. If it's your beego framework or an older version, you'll need to upgrade Beego:

Go get-u github.com/astaxie/beego
Go get-u Github.com/beego/bee

View the latest version of Bee:

Bee version

| ___ \| |_/ /  ___   ___| ___ \ / _ \ / _ \| |_/ /|  __/|  __/\____/  \___| \___| v1.5.2├── Beego     : 1.7.1├── GoVersion : go1.7.3├── GOOS      : darwin├── GOARCH    : amd64├── NumCPU    : 8├── GOPATH    : /Users/jjz/Documents/go├── GOROOT    : /usr/local/Cellar/go/1.7.3/libexec├── Compiler  : gc└── Date      : Saturday, 26 Nov 2016

You can see the environment configuration of Go, the version of Beego, and other information from this command.

Creating a Document

conf/app.confafter you set up in EnableDocs=true , you can still generate documents from commands:

Bee Generate Docs

Just what is generated here is no longer docs.go , but conforms to swagger the two documents used:

swagger.jsonswagger.yml

swagger.ymlis a contract document for swagger, which, according to this document, describes the definition rules for the API. It swagger.json describes an API data that conforms to the swagger rules, which can be used to swagger-ui list API documents in.
The bee generate docs command can be used to generate two swagger files for the, but the Bee project runs by monitoring files, automatically recompiling the project, automatically recompiling the project can also automatically generate the document is the best, so beego to run the project when the automatic generation of documents to add the command:

Bee Run-gendoc=true

This allows you to update the API documentation each time the project is rerun without running the command again: bee generate docs .

Access to API documentation

Updating swagger-ui is a very troublesome thing, so add a parameter to the Beego Run command -downdoc=true :

Bee Run-downdoc=true

The command will monitor if swagger there are any swagger-ui files under the directory, and if not, download from GitHub, the address is: Https://github.com/beego/swagger/archive/v2.zip
In addition, the method of setting the static folder has changed, and the new function is:

Beego. Setstaticpath ("/swagger", "swagger")

After you set up the static folder, you can access the swagger document through url:http://127.0.0.1:8080/swagger/index.html. Opening the document will automatically request swagger.json that the requested swagger.json document address is: Http://127.0.0.1:8080/swagger/index.html/swagger.json, need to put swagger/index.html The address of the Swagger.json in is set to:

url = "/swagger/swagger.json";

Visit the Swagger document address again to see the API documentation:

Swagger documentation

Routing parsing and annotations

Route resolution is still used namespace+Include :

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

Annotations are still used in previous annotations:

// @Title createUser// @Description create users// @Param    body        body     models.User    true        "body for user content"// @Success 200 {int} models.User.Id// @Failure 403 body is 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()}

Summarize

The new version of the Beego in the support of swagger more friendly, but also more swagger, the use of swagger.json and swagger.yml files, do not need to regenerate a new router file, so that the document part of the code more separation, using swagger.yml It is more convenient to generate code in other languages that access the API.

Source code Address: Https://github.com/jjz/go/tree/master/autodoc