目录
8.2 @ApiImplicitParams、@ApiImplicitParam：方法参数的说明
9.1 @ApiResponses、@ApiResponse：响应状态状态的说明
10.2 @ApiModelProperty 对象中每个参数的说明
1. 前后端分离的特点
前后端分离是的前端与后端之间的职责更加明确
- 后台： 负责业务处理
- 前端： 负责显示逻辑
在这种情况下，前端和后端可以分别交付给专业的开发人员去做，所以是必须要定义前后端直接的对接 接口，否则各自为是则项目无法集成，这时就需要一个文档来定义统一的接口。
2. 在没有swagger之前
在没有swagger之间，我们可以使用word，excel等功能来书写接口定义文档，但又有一个弊端，即： 在接口发送改变时需要及时的同步接口文档，否则实际的接口与接口文档不相符，则接口文件就失去了 作用，甚至会起到反作用。
3. swagger的作用
根据在代码中使用自定义的注解来生成接口文档，这个在前后端分离的项目中很重要。这样做的好处是 在开发接口时可以通过swagger将接口文档定义好，同时也方便以后的维护。
4. swagger的优点
- 号称时最流行的API框架
- 接口文档在线生成，避免同步的麻烦
- 可以支持在线对接口执行测试
- 支持多语言
5. 集成swagger
5.1 新建springboot项目
5.2 集成swagger
1. 打开https://mvnrepository.com/ ， 查找springbox，在pom.xml中导入如下图标出的依赖。
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger2</artifactId>
<version>2.9.2</version>
</dependency>
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger-ui</artifactId>
<version>2.9.2</version>
</dependency>2. 编写swagger配置类
package com.zking.mini_program.configuration;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import springfox.documentation.builders.ApiInfoBuilder;
import springfox.documentation.builders.PathSelectors;
import springfox.documentation.builders.RequestHandlerSelectors;
import springfox.documentation.service.ApiInfo;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2;
@SuppressWarnings("all")
@Configuration
@EnableSwagger2
public class SwaggerConfig {
@Bean
public Docket createRestApi() {
return new Docket(DocumentationType.SWAGGER_2).apiInfo(apiInfo())
.select()
.apis(RequestHandlerSelectors.basePackage("com.zking.mini_program.controller"))
.paths(PathSelectors.any())
.build();
}
private ApiInfo apiInfo() {
return new ApiInfoBuilder()
.title("SwaggerDemo API DOC")
.description("SwaggerDemo API DOC")
.version("1.0")
.termsOfServiceUrl("https://www.baidu.com")
.build();
}
}
注意： 该配置类需要根据自己的项目修改，如以下配置（如下有代码演示）
- paths 指定需要生成文档的url规则
- title 文档标题
- description 描述
package com.jmh.swagger.config;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import springfox.documentation.builders.ApiInfoBuilder;
import springfox.documentation.builders.PathSelectors;
import springfox.documentation.builders.RequestHandlerSelectors;
import springfox.documentation.service.ApiInfo;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2;
@SuppressWarnings("all")
@Configuration
@EnableSwagger2
public class SwaggerConfig {
@Bean
public Docket createRestApi() {
return new Docket(DocumentationType.SWAGGER_2).apiInfo(apiInfo())
.select()
.apis(RequestHandlerSelectors.basePackage("com.jmh.swagger.controller"))
.paths(PathSelectors.any())
.build();
}
private ApiInfo apiInfo() {
return new ApiInfoBuilder()
.title("贵美商城后台api")
.description("SwaggerDemo API DOC")
.version("1.0")
.termsOfServiceUrl("https://www.guimeishop.com")
.build();
}
}
5.3 开发一个controller用于测试
1. model模块
package com.jmh.swagger.model;
import io.swagger.annotations.ApiModel;
import io.swagger.annotations.ApiModelProperty;
import lombok.Data;
import java.io.Serializable;
/**
* @author 蒋明辉
* @data 2022/12/8 13:38
*/
@Data
@ApiModel(description = "用户实体类")
public class User implements Serializable {
@ApiModelProperty(value = "用户编号",example = "0")
private int id;
@ApiModelProperty(value = "用户账号",example = "张三")
private String name;
@ApiModelProperty(value = "用户密码",example = "123")
private String pwd;
}
2. controller模块
package com.jmh.swagger.controller;
import com.jmh.swagger.model.User;
import io.swagger.annotations.*;
import org.springframework.web.bind.annotation.*;
/**
* @author 蒋明辉
* @data 2022/12/8 13:36
*/
@RestController
@RequestMapping("/user")
@Api(tags = "用户操作类")
public class UserController {
@ApiOperation(value = "用户登录方法")
@RequestMapping(value = "/login",method = RequestMethod.POST)
@ApiResponses({
@ApiResponse(code = 200, message = "请求成功"),
@ApiResponse(code = 400, message = "请求参数没填好"),
@ApiResponse(code = 404, message = "请求路径没有或页面跳转路径不对")
})
public User login(@RequestBody User user){
return user;
}
@ApiOperation(value = "根据用户编号删除方法")
@RequestMapping(value = "/delById",method = RequestMethod.DELETE)
@ApiImplicitParam(value = "用户编号",name = "id",paramType = "query",required = true)
public int delById(int id){
return id;
}
@PostMapping("/register")
@ApiOperation(value = "用户注册方法")
@ApiImplicitParams({
@ApiImplicitParam(value = "用户账号",name = "name",paramType = "query",required = true),
@ApiImplicitParam(value = "用户密码",name = "pwd",paramType = "query",required = true),
@ApiImplicitParam(value = "用户编号",name = "id",paramType = "query",required = true)
})
public String register(
@RequestParam("name") String name,
@RequestParam("pwd") String pwd,
@RequestParam("id") String id){
return null;
}
}
5.4 启动服务，验证集成效果
服务启动后，访问：http://localhost:8080/swagger-ui.html
说明集成成功
如果启动项目报错 Failed to start bean ‘documentationPluginsBootstrapper （解决如下， 2选1）
- 切换springboot版本为（2.5.11）
- 在application配置文件里面加上
spring:
mvc:
pathmatch:
matching-strategy: ant_path_matcher6. swagger2 注解整体说明
6.1 请求类的描述
| 注解 | 说明 |
|---|---|
| @Api | 对于请求类的说明 |
6.2 方法和方法参数的描述
| 注解 | 说明 |
|---|---|
| @ApiOperation | 方法的说明 |
| @ApiImplicitParams | 方法参数的说明； |
| @ApiImplicitParam | 用于指定单个参数的说明。 |
6.3 方法的响应状态的描述
| 注解 | 说明 |
|---|---|
| @ApiResponses | 方法返回值的说明 ； |
| @ApiResponse | 用于指定单个参数的说明。 |
6.4 对象的描述
| 注解 | 说明 |
|---|---|
| @ApiModel | 用在JavaBean类上，说明JavaBean的 整体用途 |
| @ApiModelProperty | 用在JavaBean类的属性上面，说明此属性的的含议 |
7. 请求类的描述
7.1 @Api：请求类的说明
@Api：放在 请求的类上。与 @Controller 并列，说明类的作用，如用户模块，订单类等。
tags="说明该类的作用"
value="该参数没什么意义，所以不需要配置"
7.2 示例
@Api(tags="订单模块")
@Controller
public class OrderController {
}
@Api 其它属性配置：
| 注解 | 说明 |
|---|---|
| value | url的路径值 |
| tags | 如果设置这个值、value的值会被覆盖 |
| description | 对api资源的描述 |
| basePath | 基本路径 |
| position | 如果配置多个Api 想改变显示的顺序位置 |
| produces | 如, “application/json, application/xml” |
| consumes | 如, “application/json, application/xml” |
| protocols | 协议类型，如: http, https, ws, wss. |
| authorizations | 高级特性认证时配置 |
| hidden | 配置为true ，将在文档中隐藏 |
8. 方法和方法参数的描述
8.1 @ApiOperation：方法的说明
@ApiOperation："用在请求的方法上，说明方法的作用"
value="说明方法的作用"
notes="方法的备注说明"
8.2 @ApiImplicitParams、@ApiImplicitParam：方法参数的说明
@ApiImplicitParams：用在请求的方法上，包含一组参数说明
@ApiImplicitParam：对单个参数的说明
name：参数名
value：参数的说明、描述
required：参数是否必须必填
paramType：参数放在哪个地方
· query --> 请求参数的获取：@RequestParam
· header --> 请求参数的获取：@RequestHeader
· path（用于restful接口）--> 请求参数的获取：@PathVariable
· body（请求体）--> @RequestBody User user
· form（普通表单提交）
dataType：参数类型，默认String，其它值dataType="Integer"
defaultValue：参数的默认值
8.3 示列
@Api(tags="用户模块")
@Controller
public class UserController {
@ApiOperation(value="用户登录",notes="随边说点啥")
@ApiImplicitParams({
@ApiImplicitParam(name="mobile",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 JsonResult login(@RequestParam String mobile, @RequestParam String password, @RequestParam Integer age){
//...
return JsonResult.ok(map);
}
}
9. 响应状态的描述
9.1 @ApiResponses、@ApiResponse：响应状态状态的说明
@ApiResponses：响应状态的说明。是个数组，可包含多个 @ApiResponse
@ApiResponse：每个参数的说明
code：数字，例如400
message：信息，例如"请求参数没填好"
response：抛出异常的类
9.2 示例
@Api(tags="用户模块")
@Controller
public class UserController {
@ApiOperation("获取用户信息")
@ApiImplicitParams({
@ApiImplicitParam(paramType="query", name="userId", dataType="String", required=true, value="用户Id")
})
@ApiResponses({
@ApiResponse(code = 200, message = "请求成功"),
@ApiResponse(code = 400, message = "请求参数没填好"),
@ApiResponse(code = 404, message = "请求路径没有或页面跳转路径不对")
})
@ResponseBody
@RequestMapping("/list")
public JsonResult list(@RequestParam String userId) {
...
return JsonResult.ok().put("page", pageUtil);
}
}
10. 对象的描述
10.1 @ApiModel：对象的整体说明
@ApiModel 经常用于请求的入参对象和 响应返回值对象的描述。
- 入参是对象，即
@RequestBody时， 用于封装请求（包括数据的各种校验）数据； - 返回值是对象，即
@ResponseBody时，用于返回值对象的描述。
@ApiModel(description = "用户登录")
public class UserLoginVO implements Serializable {
}
10.2 @ApiModelProperty 对象中每个参数的说明
@ApiModelProperty 用于每个属性上面，说明属生的含义。
@ApiModel
public class UserLoginVO implements Serializable {
@ApiModelProperty(value = "用户名",required=true)
private String username;
}
10.3 示例
1）入参是对象，即 @RequestBody 时， 用于封装请求
@ApiModel(description = "用户登录")
public class UserLoginVO implements Serializable {
private static final long serialVersionUID = 1L;
@ApiModelProperty(value = "用户名",required=true)
private String username;
@ApiModelProperty(value = "密码",required=true)
private String password;
// getter/setter省略
}
2）返回值是对象，即 @ResponseBody 时，用于返回值对象的描述。
@ApiModel(description= "返回响应数据")
public class JsonResult implements Serializable{
@ApiModelProperty(value = "是否成功",required=true)
private boolean success=true;
@ApiModelProperty(value = "错误码")
private Integer errCode;
@ApiModelProperty(value = "提示信息")
private String message;
@ApiModelProperty(value = "数据")
private Object data;
/* getter/setter 略*/
}
3） UserLoginVO 和 JsonResult 的使用
UserLoginVO 作为入参对象。
JsonResult 作为返回值对象。
@Api(tags="用户模块")
@Controller
public class UserController {
@ApiOperation(value = "用户登录", notes = "")
@ResponseBody
@PostMapping(value = "/login")
public JsonResult login(@RequestBody UserLoginVO userLoginVO) {
User user=userSerivce.login(userLoginVO);
return new JsonResult("1","成功");
}
}