# Swagger
![详细对比:Spring REST Docs 与 Swagger 之间的区别](https://apifox.com/apiskills/content/images/2024/05/apiskills---15.png)
详细对比:Spring REST Docs 与 Swagger 之间的区别
当我们将 Spring REST 文档与 Swagger 进行比较时,我们需要了解它们的的区别,并比较它们的优势,最终确定哪种工具是满足我们的 API 文档需求的最佳选择。
![使用 Springfox 为 Spring 应用程序生成 Swagger-2 API 文档](https://apifox.com/apiskills/content/images/2023/10/Springfox-Spring-Swagger-2-API.png)
使用 Springfox 为 Spring 应用程序生成 Swagger-2 API 文档
Springfox 是一组 Java 库,它演变自 swagger-springmvc 项目。它自动生成使用 Spring 框架实现的 JSON API 的规范。同时,它提供与 API 交互的 Swagger UI 集成的库。
![使用装饰器为 Koa APIs 创建Swagger 文档](https://apifox.com/apiskills/content/images/2023/10/Koa-APIs-create-Swagger-document.png)
使用装饰器为 Koa APIs 创建Swagger 文档
装饰器是一个可以附加到类、方法、属性等的函数,并在运行时调用,提供有关所附加到的声明的详细信息(让我们称之为装饰实体)。
![使用 OpenAPI 3.0 规范记录 RESTAPI 时需要考虑的这 10 点](https://apifox.com/apiskills/content/images/2023/10/OpenAPI-3.0-RESTAP-10.png)
使用 OpenAPI 3.0 规范记录 RESTAPI 时需要考虑的这 10 点
本文将列出主要的升级过程中的要点和使用 OAS 3 记录 API 的要点。其中一些要点可能仍适用于之前的 OAS 2(前称 Swagger)文档,但值得一提,因为我之前没有充分注意到它们。
![如何用 Swagger UI 和 JSDoc 编写 Express API 文档](https://apifox.com/apiskills/content/images/2023/10/Swagger-UI-JSDoc-Express-API.png)
如何用 Swagger UI 和 JSDoc 编写 Express API 文档
Swagger 提供了一种用于展示这些文档的工具:Swagger UI。Swagger UI 可以根据 OpenAPI 规范定义创建一个网页。正如本教程将展示的那样,这些定义可以直接在 JSDoc 注释中使用 YAML 编写。
![如何使用 Swagger 生成 Node.js API 文档](https://apifox.com/apiskills/content/images/2023/10/Swagger-Node.js-API.png)
如何使用 Swagger 生成 Node.js API 文档
为了开始编写 API 规范,我们将使用 Node.js 构建我们的 API,Node.js 是一个后端 JavaScript 运行时环境,它在 V8 JavaScript 引擎上运行,并在 Web 浏览器之外执行 JavaScript 代码。
![Swagger 注解 @Authorization 和 @AuthorizationScope 的用法](https://apifox.com/apiskills/content/images/2023/10/Swagger-@Authorization-@AuthorizationScope.png)
Swagger 注解 @Authorization 和 @AuthorizationScope 的用法
@Authorization 和@AuthorizationScope 是 Swagger 提供的两个安全性相关的注解,用于在 Swagger UI 界面添加安全授权信息。
![Swagger 注解 @ApiParam 的用法](https://apifox.com/apiskills/content/images/2023/10/Swagger-@ApiParam.png)
Swagger 注解 @ApiParam 的用法
@ApiParam 注解用于给控制器类方法的参数添加元数据信息,这些信息会在 Swagger 生成的 API 文档中显示。它通常用于描述参数的含义、作用、参数类型、默认值等,方便使用者更好地理解接口参数。
![Swagger 注解 @ApiImplicitParams 和 @ApiImplicitParam 的用法](https://apifox.com/apiskills/content/images/2023/10/Swagger-@ApiImplicitParams-@ApiImplicitParam.png)
Swagger 注解 @ApiImplicitParams 和 @ApiImplicitParam 的用法
@ApiImplicitParams 用于定义多个参数,而@ApiImplicitParam 用于定义单个参数。这两个注解的作用都是描述接口的参数信息,使 Swagger 可以正确解析接口的参数并在 Swagger UI 中生成参数文档。
![Swagger 注解 @ApiResponses 和 @ApiResponse 的用法](https://apifox.com/apiskills/content/images/2023/10/Swagger-@ApiResponses-@ApiResponse.png)
Swagger 注解 @ApiResponses 和 @ApiResponse 的用法
@ApiResponses 和 @ApiResponse 是 Swagger 提供的两个注解,用于定义 API 接口的响应信息,包括状态码、描述信息等。它们可以更好地描述和说明 API 接口的返回结果,提供更清晰、准确的文档和信息。
![Swagger 注解 @ApiModel 和 @ApiModelProperty 的用法](https://apifox.com/apiskills/content/images/2023/10/Swagger-@ApiModel-@ApiModelProperty.png)
Swagger 注解 @ApiModel 和 @ApiModelProperty 的用法
@ApiModel 注解用于描述一个模型,可以用在类上。@ApiModelProperty 注解则用于描述模型的属性,可以用在属性上。
![Swagger 中的 @ApiOperation 注解用法](https://apifox.com/apiskills/content/images/2023/10/Swagger-@ApiOperation.png)
Swagger 中的 @ApiOperation 注解用法
@ApiOperation 是 Swagger 提供的一种注解,主要用于描述 API 的作用和目的。它是 Swagger 文档生成工具中的核心注解之一,通过它可以方便地生成 API 文档,提高 API 的可读性和可维护性。
![Swagger 中接口如何排序?](https://apifox.com/apiskills/content/images/2023/10/Swagger-api-sort.png)
Swagger 中接口如何排序?
Swagger 提供了接口排序的功能,我们可以通过配置注解来实现 API 的排序,使得 API 文档更加清晰、易读。
![Swagger map 类型参数使用详解](https://apifox.com/apiskills/content/images/2023/10/Swagger-map.png)
Swagger map 类型参数使用详解
在 Swagger 中,map 类型参数用于表示一个键值对的集合,类似于 Java 中的 Map。map 类型参数在 API 文档中通常用于描述一组可选或动态的参数,使得接口更加灵活和可扩展。
![Swagger 接口分组配置教程](https://apifox.com/apiskills/content/images/2023/10/Swagger-api-Group-.png)
Swagger 接口分组配置教程
当项目中存在多个模块或多个版本的接口时,使用 Swagger 接口分组功能可以更好地组织和管理这些接口。
![Swagger enum 使用详解](https://apifox.com/apiskills/content/images/2023/10/Swagger-enum.png)
Swagger enum 使用详解
enum 是 Swagger 规范中用来定义枚举类型的一种方式。它允许开发者在 API 文档中明确列出该接口的参数、返回值或请求体中可接受的枚举值。