1.1.1 什么是Swagger
目前是比较主流的风格的文档工具，做过开发的人应该都用过它
它提供了一套工具和规范，让开发人员能够更轻松地创建和维护可读性强、易于使用和交互的API文档（官方口吻）。
1.1.2 为什么用Swagger
- 最重要的一点可以根据代码注解自动生成文档，能生成的绝对不手写，而且文档与API定义会同步更新。
- 它提供了一个可执行的界面，支持在线测试，可以直接在界面上直接设置参数测试，不用额外的测试工具或插件。
- 支持多种编程语言， 等语言都支持，喜欢什么语言构建API都行。
1.2.1 Swagger2
Swagger2 ，访问路径：http://127.0.0.1:8080/swagger-ui.html
1.2.1.1 pom.xml
1.2.1.2 Swagger2 配置
创建配置类，类标注注解是关键，到这最简单的文档环境就搭建好了。
1.2.2 Swagger3
Swagger3，访问路径：http://127.0.0.1:8080/swagger-ui/index.html
1.2.2.1 pom.xml
1.2.2.2 Swagger3 配置
1.2.2.3 Swagger3 启动报错
启动时可能会报如下的错误，这是由于高版本的 与版本使用的路径匹配策略冲突导致的。
使用的路径匹配规则为 的，而使用的是，两者冲突了。
解决方案：
- 降低版本
版本降低到 、降到 以下可以解决问题 - 统一路径匹配策略
将的匹配路径的策略改为，文件增加如下的配置：
- 注册
也可以自行实现兼容逻辑来解决这个问题，我们可以在容器中注册一个，在该处理器中对 进行定制。
通过过滤掉已存在的映射，意味着我们可以将特定的添加到列表中，从而使用自定义的设置来替代原有的。
这样修复了可能导致无法正常使用的问题。
1.3.1 select
返回一个对象，是使用、两个方法的前提，用于指定要扫描的接口和路径。
1.3.2 apis
默认情况下，会扫描整个项目中的接口，通过 方法，你可以传入一个对象实例来指定要包含的接口所在的包路径。
1.3.3 paths
仅将某些特定请求路径的展示在文档中，例如路径中包含。可以使用 和 方法一起来过滤接口。
1.3.4 groupName
为生成的文档指定分组的名称，用来区分不同的文档组。
实现文档的多个分组，则需创建多个 实例，设置不同的组名，和组内过滤 的条件。
1.3.5 apiInfo
设置API文档的基本信息，例如标题、描述、版本等。可以使用ApiInfo对象自定义信息。
1.3.6 enable
启用或禁用 文档的生成，有时测试环境会开放API文档，但在生产环境则要禁用，可以根据环境变量控制是否显示。
1.3.7 host
文档显示的主机名称或IP地址，即在测试执行接口时使用的IP或域名。
1.3.8 securitySchemes
配置安全认证方式，比如常见的在中设置如、、等鉴权字段，对象中字段含义分别是别名、鉴权字段key、鉴权字段添加的位置。
这样配置后，文档将会包含一个按钮，供用户输入我们设定的 、、进行身份验证。
1.3.9 securityContexts
方法中虽然设置了鉴权字段，但此时在测试接口的时候不会自动在 中加上鉴权字段和值，还要配置的安全上下文，指定哪些接口需要进行安全认证。
1.3.10 tags
为文档中的接口添加标签，标签可以用来对进行分类或分组，并提供更好的组织和导航功能。
1.3.11 globalOperationParameters
是一个配置选项，用于定义全局的操作参数。它允许在所有 操作中共享相同的参数，而不需要在每个操作中重复定义。
是一个数组，可以包含多个参数对象。
通过在 配置文件中定义全局操作参数，可以确保这些参数在所有 操作中自动应用，并避免了重复定义相同的参数。这样可以提高代码维护性和可读性，并减少错误和冗余代码。
1.4.1 引入maven依赖
的安全登录是基于实现的，引入相关的依赖。
1.4.2 登录配置
文件中配置登录swagger的用户名和密码。
再次访问文档就会出现如下的登录页
当我们希望在文档中提供详细和完整的内容时，还可以使用其他许多内置注解来进一步丰富和定制API文档。
1.5.1 @ApiIgnore
原本可以根据指定路径或者包路径来提供，也可以使用粒度更细的注解，来实现某个在文档中。
1.5.2 @ApiModel
在接口中，只要使用实体作为参数或响应体，就会自动扫描到它们，但发现目前这些实体缺乏详细的描述信息。为了让使用者通俗易懂，需要使用提供的注解为这些实体添加详细的描述。
注解的使用在上，提供对额外信息的描述。
1.5.3 @ApiModelProperty
注解为实体类中的属性添加描述，提供了字段名称、是否必填、字段示例等描述信息。
1.5.4 @Api
注解用于标记一个控制器（）类，并提供接口的详细信息和配置项：
- ： 接口的描述信息，由于版本版本原因，可能会不生效可以使用
- ：该 是否在 文档中隐藏
- ： 的标签，如果此处与 中设置的标签一致，则会将该 放入到这个标签组内
- ：鉴权配置，配合 注解控制权限范围或者特定密钥才能访问该
- ：的响应内容类型，例如 application/json。
- ：的请求内容类型，例如 application/json。
- ：支持的通信协议。
1.5.5 @ApiOperation
该注解作用在接口方法上，用来对一个操作或方法进行描述：
- ：对接口方法的简单说明
- ：对操作的详细说明。
- ：请求方式
- ：状态码，默认为 200。可以传入符合标准的。
- ：在文档中隐藏该接口
- ：返回的对象
- ：使用该注解后，该接口方法会单独进行分组
- ：API的响应内容类型，例如 application/json。
- ：API的请求内容类型，例如 application/json。
- ：API支持的通信协议。
- ：鉴权配置，配合 注解控制权限范围或者特定密钥才能访问该API。
- ：响应的header内容
1.5.6 @ApiImplicitParams
注解用在方法上，以数组方式存储，配合 注解使用。
1.5.7 @ApiImplicitParam
- ：参数名称
- ：参数的简短描述
- ：是否为必传参数
- ：参数类型，可以为类名，也可以为基本类型（String，int、boolean等）
paramType：参数的传入（请求）类型，可选的值有 path、query、body、header、form。
1.5.8 @ApiParam
也是对方法中的单一参数进行注解，其内部属性和注解相似。
1.5.9 @ApiResponses
注解可用于描述请求的状态码，作用在方法上，以数组方式存储，配合 注解使用。
1.5.10 @ApiResponse
注解描述一种请求的状态信息：
- ：请求响应码。
- ：响应的文本消息
- ：返回类型信息。
- ：如果返回类型为容器类型，可以设置相应的值。有效值为 、 、其他任何无效的值都会被忽略。
版权声明：
本文来自互联网用户投稿，该文观点仅代表作者本人，不代表本站立场。本站仅提供信息存储空间服务，不拥有所有权，不承担相关法律责任。
如若内容造成侵权、违法违规、事实不符，请将相关资料发送至xkadmin@xkablog.com进行投诉反馈，一经查实，立即处理！
转载请注明出处，原文链接：https://www.xkablog.com/rfx/44731.html