一、swagger简介
1、前后端分离的特点
前后端分离是的前端与后端之间的职责更加明确
后台: 负责业务处理
前端: 负责显示逻辑
在这种情况下,前端和后端可以分别交付给专业的开发人员去做,所以是必须要定义前后端直接的对接接口,否则各自为是则项目无法集成,这时就需要一个文档来定义统一的接口。
2、 在没有swagger之前
在没有swagger之间,我们可以使用word,excel等功能来书写接口定义文档,但又有一个弊端,即:
在接口发送改变时需要及时的同步接口文档,否则实际的接口与接口文档不相符,则接口文件就失去了作用,甚至会起到反作用。
3、swagger的作用
根据在代码中使用自定义的注解来生成接口文档,这个在前后端分离的项目中很重要。这样做的好处是在开发接口时可以通过swagger将接口文档定义好,同时也方便以后的维护。
4、 swagger的优点
①、号称时最流行的API框架
②、接口文档在线生成,避免同步的麻烦
③、可以支持在线对接口执行测试
④、支持多语言
二、集成swagger
1、新建springboot项目
我就用了上期项目进行演示:微信程序开发之小程序交互_爱嘤斯塔的博客-CSDN博客
2、集成swagger
①、 打开https://mvnrepository.com/search?q=springfox&__cf_chl_f_tk=zlPqPT9H1JT8hcQO6TabU.rJEvDSdQvb6OLZemvXjH4-1646986778-0-gaNycGzNBlEhttps://mvnrepository.com/https://mvnrepository.com/search?q=springfox&__cf_chl_f_tk=zlPqPT9H1JT8hcQO6TabU.rJEvDSdQvb6OLZemvXjH4-1646986778-0-gaNycGzNBlE, 查找springbox,在pom.xml中导入如下图标出的依赖。
<!-- https://mvnrepository.com/artifact/io.springfox/springfox-swagger2 -->
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger2</artifactId>
<version>2.9.2</version>
</dependency>
<!-- https://mvnrepository.com/artifact/io.springfox/springfox-swagger-ui -->
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger-ui</artifactId>
<version>2.9.2</version>
</dependency>
②、编写swagger的配置类
注意: 该配置类需要根据自己的项目修改,如以下配置
paths 指定需要生成文档的url规则
title 文档标题
description 描述
package com.lv.code.config;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.web.bind.annotation.RestController;
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;
@Configuration
@EnableSwagger2
public class SwaggerConfig {
@Bean
public Docket createRestApi() {
return new Docket(DocumentationType.SWAGGER_2).apiInfo(apiInfo())
.select()
// 请求处理选择器,扫描controller层
.apis(RequestHandlerSelectors.basePackage("com.lv.code.controller"))
// 上面包内的所有请求
.paths(PathSelectors.any())
.build();
}
//api简介
private ApiInfo apiInfo() {
return new ApiInfoBuilder()
.title("l蹦跶v")
.description("SwaggerDemo API DOC")
.version("1.0")
.termsOfServiceUrl("https://www.bd.com")
.build();
}
}
启动进入:
在controller层方法内指定提交方法:
@RequestMapping("/login",method= RequestMethod.POST)
public ResponseResult<?> login(@RequestBody User user){
return userService.findUserByAccount(user);
}
可以尝试连接:
填完数据连接:
访问成功:
3、swagger常用注解
注解 | 位置 | 作用 | 参数 |
@Api | 类 | 标识这个类是swagger的资 源 | 源 tags:说明该类的作用,参数是个数组,可以填多个。 |
value="该参数没什么意 义,在UI界面上不显示,所以不用配置" | |||
description = "用户基本信息操作" | |||
@ApiOperation | 方法 | 表示一个http请求的操作 | value="方法的用途和作 用" |
notes="方法的注意事项和备注" | |||
tags:说明该方法的作用, 参数是个数组,可以填多 个。 | |||
格式:tags={"作用1","作用2"} | |||
@ApiParam | 方法, 参数 | 对参数使用说明(如:说明 或是否必填等) | value="用户名" 描述参数的意义 |
name="name" 参数的变量名 | |||
required=true 参数是否必选 | |||
@ApiModel | 类 | 表示对类进行说明,用于参 数用实体类接收,一般用在DTO上 | description="描述实体的作用" |
@ApiModelProperty | 方 法, 字段 | 表示对model属性的说明 | value="用户名" 描述参数的意义 |
name="name" 参数的变量名 | |||
required=true 参数是否必选 | |||
@ApiIgnore | 类, 方 法, 参数 | 表示这个方法或者类被忽略 | 无 |
@ApiImplicitParams | 方法 | 包含多@ApiImplicitParam | |
@ApiImplicitParam | 方法 | 表示单独的请求参数 | name="参数名称" |
value="参数说明" | |||
dataType="数据类型" | |||
paramType="query" 表示 参数放在哪里 |
header 请求参数的获取:@RequestHeader
query 请求参数的获取:@RequestParam
path(用于restful接口) 请求参数的获取:@PathVariable
body(不常用)
form(不常用)defaultValue=" 参数的默认值 "
required="true" 表示参数是否必须传 |
更全面的信息可以参考官方说明文档:
swagger-annotations 1.3.10 API
例如:
package com.lv.code.controller;
import com.lv.code.pojo.User;
import com.lv.code.service.IuserService;
import com.lv.code.util.response.ResponseResult;
import io.swagger.annotations.Api;
import io.swagger.annotations.ApiImplicitParam;
import io.swagger.annotations.ApiOperation;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.scheduling.annotation.Async;
import org.springframework.web.bind.annotation.RequestBody;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RequestMethod;
import org.springframework.web.bind.annotation.RestController;
@RestController
@RequestMapping("/user")
@Api(tags = "用户操作类")
public class UserController {
@Autowired
private IuserService userService;
@ApiOperation(value = "登录方法")
@ApiImplicitParam(value="user",required = true,name = "用户信息",paramType = "body")
@RequestMapping(value="/login",method= RequestMethod.POST)
public ResponseResult<?> login(@RequestBody User user){
return userService.findUserByAccount(user);
}
}
实体类:
package com.lv.code.pojo;
import java.io.Serializable;
import java.util.Date;
import com.fasterxml.jackson.annotation.JsonFormat;
import io.swagger.annotations.ApiModel;
import io.swagger.annotations.ApiModelProperty;
import lombok.AllArgsConstructor;
import lombok.Data;
import lombok.NoArgsConstructor;
import lombok.experimental.Accessors;
import org.springframework.format.annotation.DateTimeFormat;
import javax.persistence.*;
/**
* t_user
* @author
*/
@Data
@Table(name = "t_user")
@AllArgsConstructor
@NoArgsConstructor
@Accessors(chain = true)
@ApiModel(description = "用户实体类")
public class User implements Serializable {
// 组件自增
@Id
@GeneratedValue(strategy = GenerationType.IDENTITY)
@ApiModelProperty(name = "id",value = "用户id",example = "0")
private Long id;
@ApiModelProperty(name = "account",value = "用户账号",example = "")
private String account;
@ApiModelProperty(name = "password",value = "用户密码",example = "")
private String password;
// 将前端发送的string数据转换为date类型,输出date类型
@DateTimeFormat(pattern = "yyyy-MM-dd HH:mm:ss")
// 将date类型转换为string类型,接收date类型
@JsonFormat(pattern = "yyyy-MM-dd HH:mm:ss")
@ApiModelProperty(name = "modifyTime",value = "用户修改时间",example = "2022-03-04 13:14:00")
private Date modifyTime;
// 将前端发送的string数据转换为date类型,输出date类型
@DateTimeFormat(pattern = "yyyy-MM-dd HH:mm:ss")
// 将date类型转换为string类型,接收date类型
@JsonFormat(pattern = "yyyy-MM-dd HH:mm:ss")
@ApiModelProperty(name = "createTime",value = "用户登录时间",example = "2022-03-04 13:14:00")
private Date createTime;
private static final long serialVersionUID = 1L;
}
备注成功: