Skip to main content

Generating Swagger Files

Overview​

As we know, beego framework provides support for generateing swagger file in order to clearify the api via the command line tool called "bee". Casdoor is built based on beego too. However, we found that the swagger files generated by bee failed to categorize the apis with "@Tag" label, so we modified the original bee to implement the function.

How to write the comment​

Most rules are exactly identical to the original bee comment formats, and the only discrepancy is that the api shall be divided into different groups according to the "@Tag" label, therefore developers are obliged to ensure that this tag is correctly added. Here is an example:

// @Title Login
// @Tag Login API
// @Description login
// @Param   oAuthParams     query    string  true        "oAuth parameters"
// @Param   body    body   RequestForm  true        "Login information"
// @Success 200 {object} controllers.api_controller.Response The Response object
// @router /login [post]
func (c *ApiController) Login() {

api with same "@Tag" labels will be put into the same group.

How to generaete the swagger file​

  1. write comments for api in correct format
  2. fetch this repository https://github.com/casbin/bee
  3. build the modified bee, for example, in the root directory of casbin/bee, run 
go build -o mybee .
  1. copy mybee to the base directory of casdoor
  2. in that directory, run
mybee generate docs

Then you will find the new swagger files are generated.