Skip to main content

Generating Swagger Files

Overview​

As we know, the beego framework provides support for generating swagger files to clarify the API via the command line tool called "bee". Casdoor is also built based on beego. However, we found that the swagger files generated by bee failed to categorize the APIs with the "@Tag" label. So, we modified the original bee to implement this function.

How to write the comment​

Most rules are exactly identical to the original bee comment formats. 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() {

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

How to generate the swagger file​

  1. Write comments for the API in the 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 the following command:

    go build -o mybee .

  4. Copy mybee to the base directory of casdoor.

  5. In that directory, run the following command:

    mybee generate docs

  6. (Optional) If you want to generate swagger document for specific tags or apis, here are some example commands:

    mybee generate docs --tags "Adapter API"
    mybee generate docs --tags "Adapter API,Login API"
    mybee generate docs --apis "add-adapter"
    mybee generate docs --apis "add-adapter,delete-adapter"

    Notably: We only accept a comma , as the separator when multiple tags/apis provided.

Then you will find that the new swagger files are generated.