springboot项目配置swagger2示例详解
作者:小志的博客 时间:2021-09-01 04:24:47
swagger简介
Swagger是一款RESTful接口的文档在线自动生成、功能测试功能框架。一个规范和完整的框架,用于生成、描述、调用和可视化RESTful风格的Web服务,加上swagger-ui,可以有很好的呈现。
当我们在后台的接口修改了后,swagger可以实现自动的更新,而不需要人为的维护这个接口进行测试。
一、swagger2中常用的注解作用
注解 | 作用 |
---|---|
@Api | 修饰整个类,描述Controller的作用 ,表示标识这个类是swagger的资源 |
@ApiOperation | 描述一个类的一个方法,或者说一个接口,表示一个http请求的操作 |
@ApiParam | 用于方法的参数,表示对参数的添加元数据 |
@ApiModelProperty | 用于方法,字段。表示对model属性的说明或者数据操作更改 |
二、springboot项目配置swagger2步骤
1、springboot项目的目录结构如下:
2、pom.xml文件引入如下配置
<!--引入web相关依赖-->
<dependency>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-starter-web</artifactId>
</dependency>
<!--引入swagger2-->
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger2</artifactId>
<version>2.9.2</version>
</dependency>
<!--引入swagger-ui-->
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger-ui</artifactId>
<version>2.9.2</version>
</dependency>
3、application.yml配置文件配置如下
server:
port: 8001 #端口
servlet:
context-path: /springSecurity #配置项目名称
4、Swagger配置文件如下:
package com.xz.springsecuritydemo.config;
import com.google.common.base.Predicate;
import io.swagger.annotations.ApiOperation;
import org.springframework.beans.factory.annotation.Value;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.http.ResponseEntity;
import springfox.documentation.builders.ApiInfoBuilder;
import springfox.documentation.builders.RequestHandlerSelectors;
import springfox.documentation.service.ApiInfo;
import springfox.documentation.service.Contact;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2;
import static com.google.common.base.Predicates.or;
import static springfox.documentation.builders.PathSelectors.regex;
/**
* @description: Swagger配置文件
* @author: xz
*/
@Configuration
@EnableSwagger2//开启Swagger2
public class SwaggerConfig {
//注入配置文件中的项目名称
@Value("${server.servlet.context-path}")
private String contextPath;
/**
* 构建 swagger2 api 文档的详细信息函数
* @return
*/
private ApiInfo initApiInfo() {
ApiInfo apiInfo = new ApiInfoBuilder()
.title("springSecurity测试项目 Platform API")//大标题
.version( "1.0.0")//版本
.description(initContextInfo())//描述
.contact(new Contact("xz", "https://wwwxz.blog.csdn.net/", "123456@qq.com"))//作者信息
.license("The System Server, Version 1.0")//网站链接显示文字
.licenseUrl("https://wwwxz.blog.csdn.net/")//网站链接
.build();
return apiInfo;
}
private String initContextInfo() {
StringBuffer sb = new StringBuffer();
sb.append("REST API 设计在细节上有很多自己独特的需要注意的技巧,并且对开发人员在构架设计能力上比传统 API 有着更高的要求。")
.append("<br/>")
.append("本文通过翔实的叙述和一系列的范例,从整体结构,到局部细节,分析和解读了为了提高易用性和高效性,REST API 设计应该注意哪些问题以及如何解决这些问题。");
return sb.toString();
}
/**
* swagger2的配置文件,这里可以配置swagger2的一些基本的内容,比如扫描的包等等
* @return
*/
@Bean
public Docket restfulApi() {
System.out.println("http://localhost:8001" + contextPath + "/swagger-ui.html");
return new Docket(DocumentationType.SWAGGER_2)
.apiInfo(initApiInfo())
.groupName("RestfulApi")
//.genericModelSubstitutes(DeferredResult.class)
.genericModelSubstitutes(ResponseEntity.class)
.useDefaultResponseMessages(true)
.forCodeGeneration(false)
.pathMapping(contextPath) // base,最终调用接口后会和paths拼接在一起
.select()
//加了ApiOperation注解的类,才生成接口文档
//.apis(RequestHandlerSelectors.withMethodAnnotation(ApiOperation.class))
//暴露接口地址的包路径(即此包下的类,才生成接口文档)
.apis(RequestHandlerSelectors.basePackage("com.xz.springsecuritydemo.modules.sys.controller"))
.paths(doFilteringRules())//自定义的过滤规则
.build();
}
/**
* 设置过滤规则
* 这里的过滤规则支持正则匹配
* @return
*/
private Predicate<String> doFilteringRules() {
return or(
regex("/testUser.*"),
regex("/hello.*")
);
}
}
5、用户实体类如下:
package com.xz.springsecuritydemo.modules.sys.entity;
import io.swagger.annotations.ApiModelProperty;
/**
* @description: 用户实体类
* @author: xz
*/
public class UserQueryCondition {
private int id;
@ApiModelProperty(value = "用户名称")
private String name;
private int age;
public int getId() {
return id;
}
public void setId(int id) {
this.id = id;
}
public String getName() {
return name;
}
public void setName(String name) {
this.name = name;
}
public int getAge() {
return age;
}
public void setAge(int age) {
this.age = age;
}
}
6、控制层代码如下:
package com.xz.springsecuritydemo.modules.sys.controller;
import com.xz.springsecuritydemo.modules.sys.entity.User;
import com.xz.springsecuritydemo.modules.sys.entity.UserQueryCondition;
import io.swagger.annotations.Api;
import io.swagger.annotations.ApiOperation;
import io.swagger.annotations.ApiParam;
import org.apache.commons.lang.builder.ReflectionToStringBuilder;
import org.apache.commons.lang.builder.ToStringStyle;
import org.springframework.web.bind.annotation.*;
/**
* @description: 控制层代码如下
* @author: xz
*/
@Api(value = "API - UserController",description = "用户模块接口详情")
@RestController
@RequestMapping("/testUser")
public class UserController {
/***
* @ApiParam 如果方法接受的是具体参数,此注解需要加到方法中的参数上
*/
@RequestMapping(value = "/queryUserByName",method = RequestMethod.GET)
@ApiOperation(value = "根据用户名称查询服务")
public void queryUserByName(@ApiParam(value = "用户username") @RequestParam(name="username",required = false, defaultValue ="tom" ) String name){
System.out.println("queryUser====="+name);
}
/***
* @ApiOperation 可用在方法头上.参数的描述容器
* @ApiModelProperty 如果方法接受的是实体,此注解需要加到实体的具体属性上
*/
@RequestMapping(value = "/queryUserAll",method = RequestMethod.GET)
@ApiOperation(value = "根据用户id、名称和年龄查询服务")
public void queryUserAll(UserQueryCondition userQueryCondition){
//利用反射工具把对象输出
System.out.println(ReflectionToStringBuilder.toString(userQueryCondition, ToStringStyle.MULTI_LINE_STYLE));
}
/***
* @ApiOperation 可用在方法头上.参数的描述容器
*/
@PostMapping(value = "/createUser")
@ApiOperation(value = "用户新增服务")
public User userCreate1(@RequestBody User user){
System.out.println(user.getName()+"----"+user.getPassword());
user.setId(1);
return user;
}
/***
* @ApiOperation 可用在方法头上.参数的描述容器
*/
@PutMapping("/{id:\\d+}")
@ApiOperation(value = "用户修改服务")
public User update(@RequestBody User user){
System.out.println(user.getId()+"======"+user.getName()+"----"+user.getPassword());
user.setId(1);
return user;
}
/***
* @ApiOperation 可用在方法头上.参数的描述容器
*/
@DeleteMapping("/{id:\\d+}")
@ApiOperation(value = "用户删除服务")
public void delete(@PathVariable String id){
System.out.println(id);
}
}
7、启动项目,如下图:
8、启动项目后,访问 http://localhost:8001/springSecurity/swagger-ui.html,如下图:
9、点击user-Controller,如下图所示:
10、点击具体某一方法,可以看到如下信息:
三、示例中使用的注解解析
1、@Api注解标注在了控制层的UserController类上,如下图画红色框的位置可以看到注解生效。
2、@ApiOperation注解标注在了控制层的UserController类的方法上,如下图画红色框的位置可以看到注解生效。
3、@ApiParam注解标注在了控制层的方法参数上,如下图画红色框的位置可以看到注解生效。
4、@ApiModelProperty注解标注在了实体中的属性上,在控制层方法接收实体对象时生效,如下图画红色框的位置可以看到注解生效。
来源:https://blog.csdn.net/li1325169021/article/details/120297805
标签:springboot,swagger2
![](/images/zang.png)
![](/images/jiucuo.png)
猜你喜欢
SpringBoot AOP使用笔记
2023-12-09 13:25:50
Spring Boot中@ConditionalOnProperty的使用方法
2021-11-27 09:07:33
java 自动生成略缩图示例代码
2021-11-11 01:27:37
理解Java中的内存泄露及解决方法示例
2023-04-24 23:19:51
![](https://img.aspxhome.com/file/2023/7/78987_0s.png)
SpringBoot中 Jackson 日期的时区和日期格式问题解决
2021-09-06 19:37:50
![](https://img.aspxhome.com/file/2023/6/67446_0s.png)
C#用timer实现背单词小程序
2022-05-15 09:29:50
![](https://img.aspxhome.com/file/2023/9/80049_0s.png)
Java数据结构之线段树的原理与实现
2021-12-17 13:30:52
![](https://img.aspxhome.com/file/2023/8/72608_0s.png)
View触发机制API实现GestureDetector OverScroller详解
2023-01-24 00:57:08
Java编程关于子类重写父类方法问题的理解
2022-05-25 05:00:32
![](https://img.aspxhome.com/file/2023/7/71837_0s.jpg)
谈谈Java中整数类型(short int long)的存储方式
2023-01-01 08:24:33
![](https://img.aspxhome.com/file/2023/9/67169_0s.png)
详解Java如何判断ResultSet结果集是否为空
2023-08-22 10:51:14
详解C#开发Android应用程序的流程
2021-08-11 21:32:59
![](https://img.aspxhome.com/file/2023/9/84409_0s.png)
spring boot实战之本地jar包引用示例
2021-11-01 20:44:45
Redis集群原理详细分析
2021-08-06 07:34:00
![](https://img.aspxhome.com/file/2023/3/64753_0s.png)
java split()使用方法解析
2023-10-18 01:59:23
![](https://img.aspxhome.com/file/2023/4/71874_0s.jpg)
java中匿名内部类详解
2022-10-06 14:56:56
C#使用RestClient调用Web API
2022-05-30 04:13:09
java 发送邮件的实例代码(可移植)
2022-09-23 15:53:44
C# task应用实例详解
2023-01-22 05:23:53
![](https://img.aspxhome.com/file/2023/3/77303_0s.png)
Android提高之使用NDK把彩图转换灰度图的方法
2023-07-22 02:00:07
![](https://img.aspxhome.com/file/2023/6/88686_0s.jpg)