swagger的访问路径（swagger接口文档怎么访问）



学习完整课程请移步 互联网 Java 全栈工程师

• 【视频】Spring Cloud Alibaba-MyShop-Swagger2 接口文档引擎

• 文档需要更新的时候，需要再次发送一份给前端，也就是文档更新交流不及时。
• 接口返回结果不明确
• 不能直接在线测试接口，通常需要使用工具，比如：
• 接口文档太多，不好管理

Swagger 也就是为了解决这个问题，当然也不能说 Swagger 就一定是完美的，当然也有缺点，最明显的就是代码植入性比较强。

增加 Swagger2 所需依赖， 配置如下：

注意： 为 Controller 包路径，不然生成的文档扫描不到接口

创建一个名为 的 Java 配置类，代码如下：

Application 中加上注解 表示开启 Swagger

在 Controller 中增加 Swagger2 相关注解，代码如下：

访问地址：http://ip:port/swagger-ui.html

Swagger 通过注解表明该接口会生成文档，包括接口名、请求方法、参数、返回信息的等等。

• ：修饰整个类，描述 Controller 的作用
• ：描述一个类的一个方法，或者说一个接口
• ：单个参数描述
• ：用对象来接收参数
• ：用对象接收参数时，描述对象的一个字段
• ：HTTP 响应其中 1 个描述
• ：HTTP 响应整体描述
• ：使用该注解忽略这个API
• ：发生错误返回的信息
• ：一个请求参数
• ：多个请求参数

说明：用在请求的类上，表示对类的说明

常用参数：

• tags="说明该类的作用，非空时将覆盖 value 的值"
• value="描述类的作用"

其他参数：

• description 对 api 资源的描述，在 1.5 版本后不再支持
• basePath 基本路径可以不配置，在 1.5 版本后不再支持
• position 如果配置多个 Api 想改变显示的顺序位置，在 1.5 版本后不再支持
• produces 设置 MIME 类型列表（output），例："application/json, application/xml"，默认为空
• consumes 设置 MIME 类型列表（input），例："application/json, application/xml"，默认为空
• protocols 设置特定协议，例：http， https， ws， wss
• authorizations 获取授权列表（安全声明），如果未设置，则返回一个空的授权值。
• hidden 默认为 false，配置为 true 将在文档中隐藏

示例：

说明：用在请求的方法上，说明方法的用途、作用

常用参数：

• value="说明方法的用途、作用"
• notes="方法的备注说明"

其他参数：

• tags 操作标签，非空时将覆盖value的值
• response 响应类型（即返回对象）
• responseContainer 声明包装的响应容器（返回对象类型）。有效值为 "List", "Set" or "Map"。
• responseReference 指定对响应类型的引用。将覆盖任何指定的response（）类
• httpMethod 指定HTTP方法，"GET", "HEAD", "POST", "PUT", "DELETE", "OPTIONS" and "PATCH"
• position 如果配置多个Api 想改变显示的顺序位置，在1.5版本后不再支持
• nickname 第三方工具唯一标识，默认为空
• produces 设置MIME类型列表（output），例："application/json, application/xml"，默认为空
• consumes 设置MIME类型列表（input），例："application/json, application/xml"，默认为空
• protocols 设置特定协议，例：http， https， ws， wss。
• authorizations 获取授权列表（安全声明），如果未设置，则返回一个空的授权值。
• hidden 默认为false， 配置为true 将在文档中隐藏
• responseHeaders 响应头列表
• code 响应的HTTP状态代码。默认 200
• extensions 扩展属性列表数组

示例：

说明：用在请求的方法上，表示一组参数说明；：用在 注解中，指定一个请求参数的各个方面

常用参数：

• name：参数名，参数名称可以覆盖方法参数名称，路径参数必须与方法参数一致
• value：参数的汉字说明、解释
• required：参数是否必须传，默认为 false （路径参数必填）
• paramType：参数放在哪个地方
  • header 请求参数的获取：
  • query 请求参数的获取：
  • path（用于 restful 接口）--> 请求参数的获取：
  • body（不常用）
  • form（不常用）
• dataType：参数类型，默认 String，其它值 dataType="Integer"
• defaultValue：参数的默认值

其他参数（）：

• allowableValues 限制参数的可接受值。1.以逗号分隔的列表 2.范围值 3.设置最小值/最大值
• access 允许从API文档中过滤参数。
• allowMultiple 指定参数是否可以通过具有多个事件接受多个值，默认为 false
• example 单个示例
• examples 参数示例。仅适用于 BodyParameters

示例：

说明：用于响应类上，表示一个返回响应数据的信息（这种一般用在 POST 创建的时候，使用 这样的场景，请求参数无法使用 注解进行描述的时候）；：用在属性上，描述响应类的属性

其他参数(@ApiModelProperty)：

• value 此属性的简要说明。
• name 允许覆盖属性名称
• allowableValues 限制参数的可接受值。1.以逗号分隔的列表 2.范围值 3.设置最小值/最大值
• access 允许从 API 文档中过滤属性。
  • notes 目前尚未使用。
• dataType 参数的数据类型。可以是类名或者参数名，会覆盖类的属性名称。
• required 参数是否必传，默认为 false
• position 允许在类中对属性进行排序。默认为 0
• hidden 允许在 Swagger 模型定义中隐藏该属性。
• example 属性的示例。
• readOnly 将属性设定为只读。
• reference 指定对相应类型定义的引用，覆盖指定的任何参数值

示例：

说明：用在请求的方法上，表示一组响应；：用在 中，一般用于表达一个错误的响应信息

常用参数：

• code：数字，例如 400
• message：信息，例如 "请求参数没填好"
• response：抛出异常的类

示例：

说明：用在请求方法中，描述参数信息

常用参数：

• name：参数名称，参数名称可以覆盖方法参数名称，路径参数必须与方法参数一致
• value：参数的简要说明。
• defaultValue：参数默认值
• required：属性是否必填，默认为 false （路径参数必须填）

以实体类为参数：

其他参数：

• allowableValues 限制参数的可接受值。1.以逗号分隔的列表 2.范围值 3.设置最小值/最大值
• access 允许从 API 文档中过滤参数。
• allowMultiple 指定参数是否可以通过具有多个事件接受多个值，默认为 false
• hidden 隐藏参数列表中的参数。
• example 单个示例
• examples 参数示例。仅适用于 BodyParameters

示例：

版权声明：

本文来自互联网用户投稿，该文观点仅代表作者本人，不代表本站立场。本站仅提供信息存储空间服务，不拥有所有权，不承担相关法律责任。
如若内容造成侵权、违法违规、事实不符，请将相关资料发送至xkadmin@xkablog.com进行投诉反馈，一经查实，立即处理！

转载请注明出处，原文链接：https://www.xkablog.com/rfx/38912.html