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.