一.简介
1.什么是swagger
Swagger是一个开放源代码软件框架，由大型工具生态系统支持，可帮助开发人员设计，构建，记录和使用RESTful Web服务。尽管大多数用户通过Swagger UI工具识别Swagger，但是Swagger工具集包括对自动文档，代码生成和测试用例生成的支持。
2.swagger的特征
1. 通过代码和注释自动生成文档。在Swagger框架下，开发人员可对服务进行归类说明，对方法，模型，返回结果等进行详细说明。方便开发人员在编写代码的同时，编写文档信息。自动生成，只需很少的编辑工作，就能获得完整的REST APIs文档
2. 提供了UI界面。既展示接口信息，又提供了参数校验，测试功能
3. 形成了文档规范，支持不同的语言
4. 提供丰富的组件。
3.swagger依赖包
<!--swagger2-->
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger2</artifactId>
</dependency>
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger-ui</artifactId>
</dependency>二.swagger常用注解
1.@Api
@Api 注解用于标注一个Controller（Class）。在默认情况下，Swagger-Core只会扫描解析具有@Api注解的类，而会自动忽略其他类别资源（JAX-RS endpoints，Servlets等等）的注解。
属性 描述
value url的路径值
tags 如果设置这个值、value的值会被覆盖
description 对api资源的描述
basePath 基本路径可以不配置
position 如果配置多个Api 想改变显示的顺序位置
produces For example, "application/json, application/xml"
consumes For example, "application/json, application/xml"
protocols Possible values: http, https, ws, wss.
authorizations 高级特性认证时配置
hidden 配置为true 将在文档中隐藏
示例代码:
@Controller
@Slf4j
@RequestMapping("/user")
@Api(tags = "人员信息 API", description = "提供人员信息相关的 Rest API")
public class UserController extends BaseController {
}2.@ApiOperation
@ApiOperation 注解在用于对一个操作或HTTP方法进行描述。具有相同路径的不同操作会被归组为同一个操作对象。不同的HTTP请求方法及路径组合构成一个唯一操作。
主要属性:
属性 描述
value url的路径值
tags 如果设置这个值、value的值会被覆盖
description 对api资源的描述
basePath 基本路径可以不配置
position 如果配置多个Api 想改变显示的顺序位置
produces For example, "application/json, application/xml"
consumes For example, "application/json, application/xml"
protocols Possible values: http, https, ws, wss.
authorizations 高级特性认证时配置
hidden 配置为true 将在文档中隐藏
response 返回的对象
responseContainer 这些对象是有效的 "List", "Set" or "Map".，其他无效
httpMethod "GET", "HEAD", "POST", "PUT", "DELETE", "OPTIONS" and "PATCH"
code http的状态码 默认 200
extensions 扩展属性
3.@ApiParam
@ApiParam作用于请求方法上，定义api参数的注解。
主要属性:
属性 描述
name 属性名称
value 属性值
defaultValue 默认属性值
allowableValues 可以不配置
required 是否属性必填
access 不过多描述
allowMultiple 默认为false
hidden 隐藏该属性
example 举例子
代码示例:
public ResponseEntity<User> getUserById(
@ApiParam(value = "ID of user that needs to be fetched", allowableValues = "range[1,10]", required = true)
@PathVariable("UserId") Long userId)4.@ApiImplicitParams、@ApiImplicitParam
@ApiImplicitParams、@ApiImplicitParam 都可以定义参数.
(1).@ApiImplicitParams：用在请求的方法上，包含一组参数说明
(2).@ApiImplicitParam：对单个参数的说明
主要属性：
属性 描述
name 参数名
value 参数的说明、描述
required 参数是否必须必填
paramType 参数放在哪个地方
query --> 请求参数的获取：@RequestParam
header --> 请求参数的获取：@RequestHeader
path（用于restful接口）--> 请求参数的获取：@PathVariable
body（请求体）--> @RequestBody User user
form（普通表单提交）
dataType 参数类型，默认String，其它值dataType="Integer"
defaultValue 参数的默认值
代码示例:
提示:根据dataTtype属性的描述我们的"手机号","密码"都是"String"类型所以我们将其省略
/**
* <pre>
* 登录API接口
* </pre>
*
* @since 2022-06-10
*/
@ApiImplicitParams({
//参数效验
@ApiImplicitParam(name="phonenum",value="手机号",required=true,paramType="form"),
@ApiImplicitParam(name="password",value="密码",required=true,paramType="form"),
@ApiImplicitParam(name="age",value="年龄",required=true,paramType="form",dataType="Integer")
})
@PostMapping("/login")
public ApiResult login(@RequestParam String mobile, @RequestParam String password,
@RequestParam Integer age){
//...
return JsonResult.ok(map);
}5.@ApiResponses、@ApiResponse
@ApiResponses、@ApiResponse进行方法返回对象的说明。
主要属性：
| 属性 | 描述 |
|---|---|
| code | 数字，例如400 |
| message | 信息，例如"请求参数没填好" |
| response | 抛出异常的类 |
代码示例:
@ApiResponses({
@ApiResponse(code = 200, message = "请求成功"),
@ApiResponse(code = 400, message = "请求参数没填好"),
@ApiResponse(code = 404, message = "请求路径没有或页面跳转路径不对")
})
@ResponseBody
@RequestMapping("/user")
public ApiResult getUser(@RequestParam String userId) {
...
}6.@ApiModel、@ApiModelProperty
@ApiModel用于描述一个Model的信息（这种一般用在post创建的时候，使用@RequestBody这样的场景，请求参数无法使用@ApiImplicitParam注解进行描述的时候）。
@ApiModelProperty用来描述一个Model的属性
使用场景
@ApiModel 用在模型类上,对模型类作注解
@ApiModelProperty 用在属性上,对属性作注解
代码演示:
/**
* <pre>
* 人员信息类
* </pre>
*
*/
@Data
@ApiModel(description= "返回人员信息")
public class UserQueryVo extends BaseEntity{
@ApiModelProperty(value = "主键", required = true)
@TableId(value = "id", type = IdType.ID_WORKER)
private Long id;
@ApiModelProperty(value = "手机号", required = true)
private String phonenum;
@ApiModelProperty(value = "密码", required = true)
private String password;
@ApiModelProperty(value = "年龄", required = true)
private Integer age;
}三、查看接口文档
在浏览器中访问端口号对应的地址即可查看接口文档
http://localhost:8442/swagger-ui.html#/
四丶 swagger3.0
ps:如果是swagger3.0，会发现该地址无法访问，其实是3.0后 swagger-ui.html的资源位置变了。
下图为swagger2.x与swagger3.0版本的区别：
解决方案：
在主程序上添加@EnableOpenApi 并且访问http://localhost:8080/swagger-ui/index.html
注意：在添加@EnableOpenApi 注解时，会报错，这是因为找不到相关依赖。
解决办法：去掉下面依赖文章来源：https://www.toymoban.com/news/detail-641981.html
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger2</artifactId>
<version>3.0.0</version>
<scope>compile</scope>
</dependency>
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger-ui</artifactId>
<version>3.0.0</version>
<scope>compile</scope>
</dependency>
添加springfox-boot-starter依赖文章来源地址https://www.toymoban.com/news/detail-641981.html
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-boot-starter</artifactId>
<version>3.0.0</version>
<dependency>到了这里，关于Swagger使用方法的文章就介绍完了。如果您还想了解更多内容，请在右上角搜索TOY模板网以前的文章或继续浏览下面的相关文章，希望大家以后多多支持TOY模板网！
