一、Swagger注释是什么
Swagger注释是一种文本注释格式，它用来描述API的各种信息，如API的请求参数、响应结果、错误信息等。有了Swagger注释，我们可以用各种工具自动生成API文档、测试用例甚至客户端代码，这大大提高了API的开发效率。
下面是一个基本的Swagger注释示例：
/** * @swagger * /api/login: * post: * summary: 用户登录 * description: 用户使用用户名和密码登录系统 * requestBody: * content: * application/json: * schema: * type: object * properties: * username: * type: string * password: * type: string * responses: * 200: * description: 登录成功 * 401: * description: 用户名或密码错误 */
上面的注释描述了一个登录API的请求参数、响应结果以及错误信息。
二、Swagger注释的结构
Swagger注释是一种自由格式的注释，但是它有一定的约定俗成的结构，下面是一个简单的Swagger注释结构示例：
/** * @swagger * /api/path: * method: * summary: API简介 * description: API详细说明 * parameters: * - name: 参数名 * in: 参数所在位置（如path、query、header等） * description: 参数说明 * required: 参数是否必须 * schema: * type: 参数类型 * requestBody: * content: * - 请求体内容类型 * schema: * type: 请求体类型 * properties: * 参数名: * type: 参数类型 * required: * - 参数1 * responses: * 状态码: * description: 描述信息 * content: * 内容类型: * schema: * $ref: 定义名称（可以引用别的定义） */
Swagger注释中最重要的元素是路径（path）和方法（method）。路径用来描述API的请求URL路径，方法用来描述API的请求方法（GET、POST等）。
Swagger注释还可以包含API的请求参数、请求体、响应结果、错误信息等内容。
三、Swagger注释的优势
1. 自动生成文档
Swagger注释可以用来自动生成API文档，这大大降低了API文档的编写工作量，同时也保证了API文档的准确性。Swagger注释可以使用各种工具自动生成API文档，如Swagger-UI、ReDoc等。
2. 自动生成测试用例
Swagger注释还可以用来自动生成API测试用例，这大大降低了测试用例编写工作量，同时也提高了测试用例的覆盖率。
3. 自动生成客户端代码
Swagger注释还可以用来自动生成API客户端代码，这使得API的使用变得更加方便快捷。有些Swagger工具可以将API描述转换为各种编程语言的客户端代码。
四、Swagger注释的实际应用
1. 使用Swagger-UI展示API文档
Swagger-UI是一个开源的API文档展示工具，它可以把Swagger注释中的API描述转换成可视化的API文档。使用Swagger-UI展示API文档非常简单，只需要在项目中引入Swagger-UI的样式和脚本文件，并提供Swagger注释描述的API描述文件即可。
下面是一个使用Swagger-UI展示API文档的示例：
API文档
<link rel="stylesheet" type="text/css" href="swagger-ui.css">
<script src="swagger-ui-bundle.js"></script>
<script src="swagger-ui-standalone-preset.js"></script>
<script>
SwaggerUIBundle({
url: "swagger.json",
dom_id: '#swagger-ui',
deepLinking: true,
presets: [
SwaggerUIBundle.presets.apis,
SwaggerUIStandalonePreset
]
})
</script>
