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