Pular para o conteúdo principal

Gerando Arquivos Swagger

Visão Geral​

Como sabemos, o framework beego oferece suporte para a geração de arquivos swagger para esclarecer a API por meio da ferramenta de linha de comando chamada "bee". Casdoor também é construído com base no beego. No entanto, descobrimos que os arquivos swagger gerados pelo bee falharam em categorizar as APIs com a etiqueta "@Tag". Então, modificamos o bee original para implementar essa função.

Como escrever o comentário​

A maioria das regras é exatamente idêntica aos formatos de comentário do bee original. A única discrepância é que a API deve ser dividida em diferentes grupos de acordo com a etiqueta "@Tag". Portanto, os desenvolvedores são obrigados a garantir que esta etiqueta seja corretamente adicionada. Aqui está um exemplo:

// @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 com as mesmas etiquetas "@Tag" serão colocadas no mesmo grupo.

Como gerar o arquivo swagger​

  1. Escreva comentários para a API no formato correto.

  2. Busque este repositório: https://github.com/casbin/bee.

  3. Construa o bee modificado. Por exemplo, no diretório raiz de casbin/bee, execute o seguinte comando:

    go build -o mybee .

  4. Copie mybee para o diretório base do casdoor.

  5. Naquele diretório, execute o seguinte comando:

    mybee generate docs

  6. (Opcional) Se você quiser gerar um documento swagger para tags ou apis específicas, aqui estão alguns comandos de exemplo:

    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"

    Notavelmente: Só aceitamos uma vírgula , como separador quando várias tags/apis são fornecidas.

Então você descobrirá que os novos arquivos swagger são gerados.