Beego automation documentation (latest version)

Time:2022-1-14

Previously, I wrote an article using beego automation API documentation:Beego automation document, with the update of beego, the method of beego automation document has also been updated after 1.7.0, and the most significant update is to remove itdocs.go, usedswagger.json, more in line with the characteristics of swagger. This article is a revision and supplement to the previous article.

Environmental requirements

You need to install the latest go locale. You can refer toEnvironment configuration of golang on Mac OS, you also need to install the latest beego framework. If your beego framework is still an old version, you need to upgrade beego:

go get -u github.com/astaxie/beego
go get -u github.com/beego/bee

To 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 and the version of beego from this command.

Document generation

stayconf/app.confMedium settingEnableDocs=trueAfter that, you can still generate documents through the command:

bee generate docs

It’s just that what’s generated here is no longerdocs.go, but in accordance withswaggerTwo documents used:

swagger.json
swagger.yml

swagger.ymlIt is the contract document of swagger. According to this document, you can describe the definition rules of API. andswagger.jsonThe description is an API data conforming to swagger rules. Through this JSON data, you canswagger-uiAPI documentation is listed in.
usebee generate docsThe command can generate two swagger files for. However, when the bee project is running, the project is automatically recompiled through monitoring files. It is best that the project can also be automatically recompiled to generate documents. Therefore, beego added the command of automatically generating documents when running the project:

bee run -gendoc=true

In this way, the API document can be updated every time the project is re run without re running the command:bee generate docs

Access to API documents

to updateswagger-uiIs a very troublesome thing, so add a parameter to beego’s run command-downdoc=true:

bee run -downdoc=true

This command will monitorswaggerIs there under the directoryswagger-uiIf not, download the file from GitHub. The download address is:https://github.com/beego/swagger/archive/v2.zip
In addition, the method of setting static folders has also changed. The new function is:

beego.SetStaticPath(“/swagger”, “swagger”)

After setting the static folder, you can use URL:http://127.0.0.1:8080/swagger/index.htmlAccess the swagger documentation. Opening the document automatically the requestswagger.json, found the requestedswagger.jsonThe document address is:http://127.0.0.1:8080/swagger/index.html/swagger.json, you need toswagger/index.htmlSwagger The address of JSON is set to:

url = “/swagger/swagger.json”;

Visit the swagger document address again to see the API document:

Route parsing and annotation

Route resolution still usesnamespace+Include

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

The previous annotation method is still adopted for annotation:

// @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()
}

summary

The support for swagger in the new version of beego is more friendly and swagger orientedswagger.jsonandswagger.ymlFile, there is no need to regenerate a new router file, so that the code of the document part can be separated and usedswagger.ymlIt is more convenient to generate code in other languages that access the API.

Source code address:https://github.com/jjz/go/tree/master/autodoc