Saltar al contenido principal

Generando archivos Swagger

Visión general​

Como sabemos, el marco de trabajo beego proporciona soporte para generar archivos swagger para aclarar la API a través de la herramienta de línea de comandos llamada "bee". Casdoor también está construido sobre beego. Sin embargo, descubrimos que los archivos swagger generados por bee no lograban categorizar las API con la etiqueta "@Tag". Por lo tanto, modificamos el bee original para implementar esta función.

Cómo escribir el comentario​

La mayoría de las reglas son exactamente idénticas a los formatos de comentarios del bee original. La única discrepancia es que la API se dividirá en diferentes grupos de acuerdo con la etiqueta "@Tag". Por lo tanto, los desarrolladores están obligados a asegurarse de que esta etiqueta se agregue correctamente. Aquí hay un ejemplo:

// @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() {

Las API con las mismas etiquetas "@Tag" se colocarán en el mismo grupo.

Cómo generar el archivo swagger​

  1. Escribe comentarios para la API en el formato correcto.

  2. Obtén este repositorio: https://github.com/casbin/bee.

  3. Construye el bee modificado. Por ejemplo, en el directorio raíz de casbin/bee, ejecuta el siguiente comando:

    go build -o mybee .

  4. Copia mybee al directorio base de casdoor.

  5. En ese directorio, ejecuta el siguiente comando:

    mybee generate docs

  6. (Opcional) Si quieres generar un documento swagger para etiquetas o apis específicas, aquí hay algunos comandos de ejemplo:

    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"

    Notablemente: Solo aceptamos una coma , como separador cuando se proporcionan múltiples etiquetas/apis.

Entonces encontrarás que se generan los nuevos archivos swagger.