前端 Swagger 注解使用指南：快速构建 API 文档

前端 Swagger 可以使用注解的方式来描述 API 接口的信息。这些注解可以帮助开发者快速地构建和维护 API 文档，提高开发效率。

在前端 Swagger 中，常用的注解有以下几种：

@api：用于描述 API 接口的基本信息，包括接口名称、请求方式、请求参数、返回值等。
@param：用于描述请求参数的信息，包括参数名称、参数类型、参数说明等。
@returns：用于描述返回值的信息，包括返回值类型、返回值说明等。
@description：用于描述接口的详细信息，包括接口功能、使用方法等。

使用注解的方式，可以让开发者在编写代码时直接添加注解，而不需要再进行繁琐的文档编写工作。同时，注解也能够提高文档的准确性和完整性，保障 API 接口的质量。

具体的注解使用方法和加在哪个地方上面可能会依赖于具体的前端框架或工具。

下面是一个使用 Swagger 注解的示例：

/**
* `@api` {get} `/users/:id` 获取用户信息
* `@apiName` GetUser
* `@apiGroup` User
* `@apiPermission` admin
*
* `@apiParam` {Number} id 用户唯一ID
*
* `@apiSuccess` {String} name 用户名
* `@apiSuccess` {String} email 邮箱
* `@apiSuccess` {String} phone 手机号
*
* `@apiError` {String} message 错误信息
*
* `@apiDescription`
* 获取指定用户的详细信息，需要管理员权限。
*/

在这个示例中，我们使用了 @api 注解来描述 API 接口的基本信息，使用 @apiParam 注解来描述请求参数信息，使用 @apiSuccess 注解来描述返回值信息，使用 @apiError 注解来描述错误信息，使用 @apiDescription 注解来描述接口的详细信息。

这些注解可以加在前端代码的注释中，通常会使用特定的注释格式，比如 JSDoc、YUIDoc 等。在使用前端 Swagger 工具时，工具会通过解析这些注释来生成 API 文档。