前后端联调神器swagger以及美观化
介绍
swagger 是一款开源的接口管理技术, 他可以让我们的接口可视化,调试,参数说明,在前后端联调中是不可缺少的开发利器。
优势
支持 API 自动生成同步的在线文档:使用 Swagger 后可以直接通过代码生成文档,不再需要自己手动编写接口
文档了,对程序员来说非常方便,可以节约写文档的时间去学习新技术。
提供 Web 页面在线测试 API:光有文档还不够,Swagger 生成的文档还支持在线测试。参数和格式都定好了,直接
在界面上输入参数对应的值即可在线测试接口。
怎么做
引入maven依赖
<dependency>
<groupId>io.swagger</groupId>
<artifactId>swagger-annotations</artifactId>
<version>${io.swagger.version}</version>
</dependency>
<dependency>
<groupId>io.swagger</groupId>
<artifactId>swagger-models</artifactId>
<version>${io.swagger.version}</version>
</dependency>
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger2</artifactId>
<version>${swagger2.version}</version>
</dependency>
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger-ui</artifactId>
<version>${swagger2.version}</version>
</dependency>
<!--这个依赖并非是swagger的 这个是让我们的swagger页面更美观-->
<dependency>
<groupId>com.github.xiaoymin</groupId>
<artifactId>knife4j-spring-boot-starter</artifactId>
<version>${knife4j.version}</version>
</dependency>
swagger 配置文件配置
# Swagger配置
swagger:
enabled: true# 是否开启swagger 正式关键关闭 false
title: 文档标题
description: 文档说明
termsOfServiceUrl: http://127.0.0.1:${server.port}/ # swagger 访问文档地址
authorName: 作者名
authorEmail: 1336809324@qq.com #作者邮箱
authorUrl: 地址
version: 1.0.1
webBasePackage: com.dubug.middleware #web项目包路径
apiBasePackage: com.dubug.middleware.controller #api接口层包路径
# knife开源的swagger ui配置
knife4j:
# 配置认证功能
basic:
# 是否开启认证 正式环境关闭
enable: true
# 用户名
username: admin
# 密码
password: 123456
配置类对应的实体类
package com.dubug.middleware.config;
import lombok.Data;
import org.springframework.boot.context.properties.ConfigurationProperties;
import org.springframework.stereotype.Component;
/**
* @Description
* @Author swagger
* @Version V1.0.0
* @Date 2021/6/1 0001
*/
@Data
@ConfigurationProperties(prefix = "swagger")
@Component
public class SwaggerProperties {
/**
* 是否启用
*/
private boolean enabled;
/**
* 标题
*/
private String title;
/**
* 文档描述
*/
private String description;
/**
* 项目路径
*/
private String termsOfServiceUrl;
/**
* 作者
*/
private String authorName;
/**
* 邮箱
*/
private String authorEmail;
/**
* 作者主页
*/
private String authorUrl;
/**
* 版本
*/
private String version;
/**
* web扫描的路径
*/
private String webBasePackage;
/**
* API扫描的路径
*/
private String apiBasePackage;
}
配置
/**
* @Description
* @Author swagger
* @Version V1.0.0
* @Date 2021/6/1 0001
*/
@Configuration
@EnableSwagger2
@EnableConfigurationProperties(value = SwaggerProperties.class)
@EnableKnife4j
@Import(BeanValidatorPluginsConfiguration.class)
@ConditionalOnProperty(value = {"swagger.enabled"}, matchIfMissing = true)
public class SwaggerConfiguration {
@Bean(value = "createRestWeb")
public Docket createRestWeb(SwaggerProperties swaggerProperties) {
return new Docket(DocumentationType.SWAGGER_2)
.apiInfo(
new ApiInfoBuilder()
.title(swaggerProperties.getTitle())
.description(swaggerProperties.getDescription())
.termsOfServiceUrl(swaggerProperties.getTermsOfServiceUrl())
.contact(new Contact(swaggerProperties.getAuthorName(),
swaggerProperties.getAuthorUrl(),
swaggerProperties.getAuthorEmail()))
.version(swaggerProperties.getVersion())
.build()).groupName("后台 Web")
.select()
//apis() 控制哪些接口暴露给swagger,
// RequestHandlerSelectors.any() 所有都暴露
// RequestHandlerSelectors.basePackage("net.xdclass.*") 指定包位置
.apis(RequestHandlerSelectors.withMethodAnnotation(ApiOperation.class)) //标记有这个注解 ApiOperation
.paths(PathSelectors.any())
.build();
}
}
放开关于swagger静态资源请求权限
/**
* @Description
* @Author config
* @Version V1.0.0
* @Date 2021/2/3 0003
*/
@Slf4j
@Configuration
public class InterceptorConfig implements WebMvcConfigurer {
@Autowired
private SwaggerProperties swaggerProperties;
/**
* 资源映射
*
* @param registry
*/
@Override
public void addResourceHandlers(ResourceHandlerRegistry registry) {
if (swaggerProperties.isEnabled()) {
registry.addResourceHandler("doc.html","swagger-ui.html").addResourceLocations("classpath:/META-INF/resources/");
registry.addResourceHandler("/webjars/**").addResourceLocations("classpath:/META-INF/resources/webjars/");
}
}
}
快速编写一个表的的增删改查
controller
package com.dubug.middleware.controller;
import com.dubug.middleware.constant.ResponseConst;
import com.dubug.middleware.entity.DbBook;
import com.dubug.middleware.mapper.DbBookMapper;
import io.swagger.annotations.Api;
import io.swagger.annotations.ApiOperation;
import io.swagger.annotations.ApiParam;
import io.swagger.annotations.ApiResponse;
import io.swagger.annotations.ApiResponses;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.util.Assert;
import org.springframework.web.bind.annotation.DeleteMapping;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.PostMapping;
import org.springframework.web.bind.annotation.RequestBody;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RequestParam;
import org.springframework.web.bind.annotation.RestController;
import javax.validation.Valid;
/**
* @Description
* @Author swagger
* @Version V1.0.0
* @Date 2021/6/22 0022
*/
@Api(tags = "图书模块", value = "SwaggerController")
@RestController
@RequestMapping("/api/swagger")
public class SwaggerController {
@Autowired
private DbBookMapper dbBookMapper;
/**
* 添加图书
*/
@ApiOperation(value = "添加图书")
@PostMapping("/insert")
public void insertBook(@Valid @RequestBody DbBook dbBook) {
dbBookMapper.insert(dbBook);
}
/**
* 修改图书
*/
@ApiOperation(value = "修改图书")
@PostMapping("/update")
public void updateBook(
@Valid @RequestBody DbBook dbBook) {
//需要验参Id
Assert.notNull(dbBook.getId());
dbBookMapper.updateByPrimaryKey(dbBook);
}
/**
* 删除图书
*/
@ApiOperation(value = "根据Id删除图书")
@DeleteMapping("/delete_by_id")
public void deleteById(
@ApiParam(name = "id", value = "图书Id", example = "1")
@RequestParam("id") String id) {
dbBookMapper.deleteByPrimaryKey(id);
}
/**
* 根据Id查询图书
*/
@ApiOperation(value = "根据Id查询图书")
@ApiResponses({
@ApiResponse(code = ResponseConst.RIGHT_CODE, message = "查询成功"),
@ApiResponse(code = ResponseConst.SYS_NOERROR, message = "查询失败")
})
@GetMapping("/select_by_id")
public DbBook selectById(
@ApiParam(name = "id", value = "图书Id", example = "1")
@RequestParam("id") String id){
return dbBookMapper.selectByPrimaryKey(id);
}
}
领域模型类
package com.dubug.middleware.entity;
import io.swagger.annotations.ApiModel;
import io.swagger.annotations.ApiModelProperty;
import lombok.AllArgsConstructor;
import lombok.Builder;
import lombok.Data;
import lombok.NoArgsConstructor;
import springfox.documentation.annotations.ApiIgnore;
import javax.validation.constraints.NotBlank;
import java.io.Serializable;
@ApiModel("图书实体对象")
@Data
@Builder
public class DbBook implements Serializable {
@ApiModelProperty(value = "书籍Id")
private String id;
@NotBlank
@ApiModelProperty(value = "图书名称",required = true)
private String bookName;
@NotBlank
@ApiModelProperty(value = "库存",required = true)
private Integer stock;
}
访问接口文档
http://{ip地址}:{项目端口}/doc.html
页面如下
swagger注解说明
@Api
模块配置,用在controller类,描述API接口
@ApiOperation
接口配置,用在方法上,描述接口方法
@ApiParam
方法参数配置,用在入参上面,描述参数
@ApiIgnore
忽略此接口不生成文档
@ApiModel
用于类 表示对类进行说明,用于参数用实体类接收,value–表示对象名,description–描述
这种一般用在post创建的时候,使用对象提交这样的场景
@ApiModelProperty()
用于方法,字段; 表示对model属性的说明或者数据操作更改
value–字段说明
name–重写属性名字
dataType–重写属性类型
required–是否必填
example–举例说明
hidden–隐藏
@ApiResponse
描述接口响应
@ApiImplicitParams
用于方法