Springboot2.x整合Swagger3.X
引入依赖
<?xml version="1.0" encoding="UTF-8"?>
<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 https://maven.apache.org/xsd/maven-4.0.0.xsd">
<modelVersion>4.0.0</modelVersion>
<parent>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-starter-parent</artifactId>
<version>2.4.1</version>
<relativePath/> <!-- lookup parent from repository -->
</parent>
<groupId>net.xdclass</groupId>
<artifactId>1024shop-manager</artifactId>
<version>0.0.1-SNAPSHOT</version>
<name>1024shop-manager</name>
<description>Demo project for Spring Boot</description>
<properties>
<java.version>11</java.version>
</properties>
<dependencies>
<dependency>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-starter-web</artifactId>
</dependency>
<dependency>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-starter-test</artifactId>
<scope>test</scope>
</dependency>
<dependency>
<groupId>org.projectlombok</groupId>
<artifactId>lombok</artifactId>
<version>1.18.16</version>
<scope>provided</scope>
</dependency>
<dependency>
<groupId>mysql</groupId>
<artifactId>mysql-connector-java</artifactId>
</dependency>
<!--mybatis plus和springboot整合-->
<dependency>
<groupId>com.baomidou</groupId>
<artifactId>mybatis-plus-boot-starter</artifactId>
<version>3.4.1</version>
</dependency>
<!-- 代码自动生成依赖 begin -->
<dependency>
<groupId>com.baomidou</groupId>
<artifactId>mybatis-plus-generator</artifactId>
<version>3.4.1</version>
</dependency>
<!-- velocity -->
<dependency>
<groupId>org.apache.velocity</groupId>
<artifactId>velocity-engine-core</artifactId>
<version>2.0</version>
</dependency>
<!-- 代码自动生成依赖 end-->
<!--接口文档自动生成-->
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-boot-starter</artifactId>
<version>3.0.0</version>
</dependency>
</dependencies>
<build>
<plugins>
<plugin>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-maven-plugin</artifactId>
</plugin>
<plugin>
<groupId>org.apache.maven.plugins</groupId>
<artifactId>maven-compiler-plugin</artifactId>
<configuration>
<source>15</source>
<target>15</target>
</configuration>
</plugin>
</plugins>
</build>
<!-- 代码库 -->
<repositories>
<repository>
<id>maven-ali</id>
<url>http://maven.aliyun.com/nexus/content/groups/public//</url>
<releases>
<enabled>true</enabled>
</releases>
<snapshots>
<enabled>true</enabled>
<updatePolicy>always</updatePolicy>
<checksumPolicy>fail</checksumPolicy>
</snapshots>
</repository>
</repositories>
<pluginRepositories>
<pluginRepository>
<id>public</id>
<name>aliyun nexus</name>
<url>http://maven.aliyun.com/nexus/content/groups/public/</url>
<releases>
<enabled>true</enabled>
</releases>
<snapshots>
<enabled>false</enabled>
</snapshots>
</pluginRepository>
</pluginRepositories>
</project>
application.properties
server.port=8081
#==============================数据库相关配置========================================
spring.datasource.driver-class-name=com.mysql.cj.jdbc.Driver
spring.datasource.url=jdbc:mysql://127.0.0.1:3306/xd_shop?useUnicode=true&characterEncoding=utf-8&useSSL=false
spring.datasource.username =root
spring.datasource.password =xdclass.net
#配置mybatis plus打印sql日志
mybatis-plus.configuration.log-impl=org.apache.ibatis.logging.stdout.StdOutImpl
#xml文件路径
mybatis-plus.mapper-locations=classpath:/mapper/**/*.xml
#配置最新全局配置文件！！！！
#mybatis-plus.config-location = classpath:mybatis-config.xml
#配置mybatis包路径
mybatis-plus.type-aliases-package=net.xdclass.shopmanager.model
#mybatis plus下划线转驼峰配置，默认就是true
mybatis-plus.configuration.map-underscore-to-camel-case=true
#配置全局默认主键类型,实体类就不用加 @TableId(value = "id", type = IdType.AUTO)
mybatis-plus.global-config.db-config.id-type=auto
#删除是1
mybatis-plus.global-config.db-config.logic-delete-value=1
#未删除是0
mybatis-plus.global-config.db-config.logic-not-delete-value=0
#如果java实体类没加注解@TableLogic，则可以配置这个，推荐这里配置
mybatis-plus.global-config.db-config.logic-delete-field=deleted
#spring.application.name=小滴课堂1024shop接口,增加中文会乱码，可以修改文件编码，或者使用yml格式
spring.application.name=1024shop
# ===== 自定义swagger配置 ===== #
swagger.enable=true
swagger.application-name= ${spring.application.name}
swagger.application-version=1.0
#swagger.application-description=1024shop电商平台管理后端接口文档
swagger.application-description=1024shop api info
配置类
SwaggerConfiguration
src/main/java/net/xdclass/shopmanager/config/SwaggerConfiguration.java
package net.xdclass.shopmanager.config;
import io.swagger.annotations.ApiOperation;
import lombok.Data;
import org.springframework.boot.context.properties.ConfigurationProperties;
import org.springframework.context.annotation.Bean;
import org.springframework.stereotype.Component;
import springfox.documentation.builders.ApiInfoBuilder;
import springfox.documentation.builders.PathSelectors;
import springfox.documentation.builders.RequestHandlerSelectors;
import springfox.documentation.oas.annotations.EnableOpenApi;
import springfox.documentation.service.ApiInfo;
import springfox.documentation.service.Contact;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
/**
* 小滴课堂,愿景：让技术不再难学
*
* @Description
* @Author 二当家小D
* @Remark 有问题直接联系我，源码-笔记-技术交流群
* @Version 1.0
**/
@Component
@Data
@ConfigurationProperties("swagger")
@EnableOpenApi
public class SwaggerConfiguration {
/**
* 是否开启swagger，生产环境一般关闭，所以这里定义一个变量
*/
private Boolean enable;
/**
* 项目应用名
*/
private String applicationName;
/**
* 项目版本信息
*/
private String applicationVersion;
/**
* 项目描述信息
*/
private String applicationDescription;
@Bean
public Docket docket(){
return new Docket(DocumentationType.OAS_30)
.pathMapping("/")
// 定义是否开启swagger，false为关闭，可以通过变量控制，线上关闭
.enable(enable)
//配置api文档元信息
.apiInfo(apiInfo())
// 选择哪些接口作为swagger的doc发布
.select()
//apis() 控制哪些接口暴露给swagger，
// RequestHandlerSelectors.any() 所有都暴露
// RequestHandlerSelectors.basePackage("net.xdclass.*") 指定包位置
// withMethodAnnotation(ApiOperation.class)标记有这个注解 ApiOperation
.apis(RequestHandlerSelectors.withMethodAnnotation(ApiOperation.class))
.paths(PathSelectors.any())
.build();
}
private ApiInfo apiInfo() {
return new ApiInfoBuilder()
.title(applicationName)
.description(applicationDescription)
.contact(new Contact("小滴课堂-二当家小D", "https://xdclass.net", "794666918@qq.com"))
.version(applicationVersion)
.build();
}
}
访问
http://localhost:8081/swagger-ui/index.html
常用注解
package net.xdclass.shopmanager.controller;
import io.swagger.annotations.Api;
import io.swagger.annotations.ApiOperation;
import io.swagger.annotations.ApiParam;
import net.xdclass.shopmanager.model.User;
import net.xdclass.shopmanager.util.JsonData;
import org.springframework.web.bind.annotation.*;
import springfox.documentation.annotations.ApiIgnore;
import springfox.documentation.spring.web.json.Json;
import java.util.ArrayList;
import java.util.List;
/**
* 小滴课堂,愿景：让技术不再难学
*
* @Description
* @Author 二当家小D
* @Remark 有问题直接联系我，源码-笔记-技术交流群
* @Version 1.0
**/
@RestController
@RequestMapping("/api/v1/user")
@Api(tags = "用户模块",value = "用户controller")
public class UserController {
@ApiOperation("用户列表")
//@RequestMapping("list")
@GetMapping("list")
public JsonData list(){
User user1 = User.builder().phone("13113772121").id(1).email("794666918@qq.com").build();
User user2 = User.builder().phone("2343232").id(2).email("79466691811@qq.com").build();
List list = new ArrayList();
list.add(user1);
list.add(user2);
return JsonData.buildSuccess(list);
}
@ApiOperation("查看用户详情")
@GetMapping("detail")
public JsonData query(@ApiParam(name = "id",value = "用户id",example = "1")
@RequestParam("id") int id){
return JsonData.buildSuccess();
}
@ApiOperation("用户登录")
@PostMapping("login")
public JsonData login(
@ApiParam(name = "phone", value = "手机号",example = "13888888888")
@RequestParam("phone") String phone,
@ApiParam(name = "pwd", value = "密码",example = "123456")
@RequestParam("pwd")String pwd){
return JsonData.buildSuccess();
}
@ApiIgnore
@ApiOperation("根据id删除用户")
@DeleteMapping("/delete/{id}")
public JsonData delById(
@ApiParam(name = "id",value = "用户id",example = "1")
@PathVariable int id){
return JsonData.buildSuccess();
}
}
APiModel和ApiModelProperty对象注解
- @ApiModel()
- 用于类 表示对类进行说明，用于参数用实体类接收，value–表示对象名，description–描述
- 这种一般用在post创建的时候，使用对象提交这样的场景
- @ApiModelProperty()
- 用于方法，字段； 表示对model属性的说明或者数据操作更改
- value–字段说明
- name–重写属性名字
- dataType–重写属性类型
- required–是否必填
- example–举例说明
- hidden–隐藏
package net.xdclass.shopmanager.request;
import io.swagger.annotations.ApiModel;
import io.swagger.annotations.ApiModelProperty;
import lombok.Data;
@ApiModel(value = "新增用户请求模型")
@Data
public class SaveUserRequest {
@ApiModelProperty(value = "主键")
private int id;
@ApiModelProperty(value = "邮箱",required = true,example = "794666918@qq.com")
private String email;
@ApiModelProperty(value = "手机号",required = false)
private String phone;
private String name;
}
controller
@RestController
@RequestMapping("/api/v1/user")
@Api(tags = "用户模块",value = "用户controller")
public class UserController {
@ApiOperation("新增用户")
@PostMapping("save")
//public JsonData save(SaveUserRequest userRequest){
public JsonData save(@RequestBody SaveUserRequest userRequest){
return JsonData.buildSuccess();
}
}
ApiResponse 描述接口响应
@ApiOperation("用户登录")
@PostMapping("login")
@ApiResponses({
@ApiResponse(responseCode = HttpCodeStatus.REDIRECT, description = "重定向,跳转登录"),
@ApiResponse(responseCode = "403",description = "没权限"),
})
public JsonData login(
@ApiParam(name = "phone", value = "手机号",example = "13888888888")
@RequestParam("phone") String phone,
@ApiParam(name = "pwd", value = "密码",example = "123456")
@RequestParam("pwd")String pwd){
return JsonData.buildSuccess();
}