Beego Automation Documentation

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

Due to the Beego update, some methods of using automated documentation have also been updated, please refer to: Http://www.jianshu.com/p/0dc261bc5cea

What is Beego?

beegois an open source project that quickly develops the HTTP framework for go Applications , the go 语言 technology Daniel Asta.
beegoCan be used to quickly develop APIs,Web and back-end services and other applications, is a RESTFul framework, the main design inspiration from tornado , sinatra flask these three frameworks, Designed to incorporate some of the features ( interface , struct inheritance, etc.) of go itself.
beegoswaggerautomate the documentation in combination.

What is swagger?

Swaggeris a specification and a complete set of frameworks for, and 生成 描述 调用 可视化 RESTful Web Services .
SwaggerThe overall goal is to keep the client and file system servers updated at the same speed, 方法，参数和模型 tightly integrated into the server-side code, and 允许API always in sync.
SwaggerMaking deployment management and using the API has never been easier.

What are the benefits of automatic documentation?

1. 不用手动写文档了，通过注解就可以自动化文档2. 文档和代码同步更新，代码更新之后不需要再更新文档3. 浏览器友好4. 使用Swagger框架可以调试API，在浏览器端可以看到更多的`request`和`response`信息

User Guide

Install go:http://www.jianshu.com/p/943870134593 First
You can use intelliJ the ide:http://www.jianshu.com/p/943870134593 as Go
You can also use Atom the ide:http://www.jianshu.com/p/c1d8cf274ec7 of the action go

Installing Beego:http://beego.me/quickstart
Using the go get installation Beego:

Go get Github.com/astaxie/beego

To install the Bee tool:

Go get Github.com/beego/bee

The unfinished side can $GOPATH/bin add to your $PATH variables:

Export path= $PATH: $GOPATH/bin

Create a Beego Project

beetools can be used to create, manage, run, and package beego projects easily:

Bee API Beeapi

You must $GOPATH/src create the project under the directory.
Specify a directory for the project Swagger :

Beego. staticdir["/swagger"] = "swagger"

Download Swagger : Https://github.com/beego/swagger
You can also download the latest Swagger : http://swagger.io/

Put 根目录 it under the project, the directory name is swagger , and the configuration above is the same.

Route resolution

At present, the routing rules of Automatic documents only support NewNamespace the parsing of writing, and the other functions do not automatically parse into the article, that is, the way to write namespace+Include . And only supports two-level resolution, where one level represents the version number, and the second level represents the application module.
Such as:

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

Generate document

Setting in the configuration file conf/app.conf

Enabledocs = True

Generate docs File:

Bee Generate Docs

The build of the document is called in the docs file, init函数 so you must import the docs file in main, which calls theinit函数

  _ "beeapi/docs"

To run the program:

Bee Run Watchall True

The bee run command is to monitor the project files of the Beego, by fsnotify monitoring the file system, so that in the process of development can be real-time to see the effect of the project after the modification.

Open http://127.0.0.1:8080/swagger/to see the interface of the automation document

Swagger

You can also change the port number of docs by running the following command:

Bee Run docs-docport=8888

Annotations

beegoThere are two types of documentation annotations: global annotations and application annotations.
全局注释, must be placed at router.go the top, including:

    @APIVersion    @Title    @Description    @Contact    @TermsOfServiceUrl    @License    @LicenseUrl

Application notes, which need to be placed on top of the corresponding methods, include:

    @title    @Description    @Param    @Success    @Failure    @router

Test Project Address: Https://github.com/jjz/go/tree/master/autodoc

Reference Document: HTTP://BEEGO.ME/DOCS/ADVANTAGE/DOCS.MD