一、Swagger简介
Swagger是一套开源工具和规范，用于设计、构建和文档化
RESTful Web服务。它允许开发人员定义API的各个方面，并生成易于理解的API文档和交互式API探索界面。同时，Swagger还提供代码生成工具，可自动生成与API交互的客户端和服务器端代码，提高开发效率。
二、SpringBoot集成Swagger
使用Swagger
要求：jdk 1.8 + 否则swagger2无法运行
步骤：
-
新建一个SpringBoot-web项目
-
添加Maven依赖
<dependency> <groupId>io.springfox</groupId> <artifactId>springfox-swagger2</artifactId> <version>2.9.2</version> </dependency> <dependency> <groupId>io.springfox</groupId> <artifactId>springfox-swagger-ui</artifactId> <version>2.9.2</version> </dependency> -
编写HelloController，测试确保运行成功！
@RestController public class HelloController { @RequestMapping("/hello") public String hello(){ return "hello swagger"; } } -
要使用Swagger，我们需要编写一个配置类
SwaggerConfig来配置 Swaggerpackage com.liming.config; import org.springframework.context.annotation.Configuration; import org.springframework.web.servlet.config.annotation.ResourceHandlerRegistry; import org.springframework.web.servlet.config.annotation.WebMvcConfigurationSupport; import springfox.documentation.swagger2.annotations.EnableSwagger2; @Configuration @EnableSwagger2// 开启Swagger2的自动配置 public class SwaggerConfig extends WebMvcConfigurationSupport { /** * 解决高版本springboot无法访问http://localhost:8001/swagger-ui.html * @param registry void */ @Override protected void addResourceHandlers(ResourceHandlerRegistry registry) { // 解决静态资源无法访问 registry.addResourceHandler("/**").addResourceLocations("classpath:/static/"); // 解决swagger无法访问 registry.addResourceHandler("/swagger-ui.html").addResourceLocations("classpath:/META-INF/resources/"); // 解决swagger的js文件无法访问 registry.addResourceHandler("/webjars/**").addResourceLocations("classpath:/META-INF/resources/webjars/"); } } -
访问测试 ：http://localhost:8080/swagger-ui.html ，可以看到swagger的界面；
三、配置Swagger
-
Swagger实例Bean是Docket，所以通过配置Docket实例来配置Swaggger。
@Bean //配置docket以配置Swagger具体参数 public Docket docket() { return new Docket(DocumentationType.SWAGGER_2); } -
可以通过apiInfo()属性配置文档信息
//配置文档信息 private ApiInfo apiInfo() { return new ApiInfoBuilder() .title("Swagger标题") // 标题 .description("学习演示如何配置Swagger") //描述 .version("v1.0") // 版本 .contact(new Contact("黎明", "https://blog.csdn.net/weixin_46370595?type=blog", "2356731504@qq.com")) .build(); } -
Docket 实例关联上 apiInfo()
@Bean public Docket docket() { return new Docket(DocumentationType.SWAGGER_2).apiInfo(apiInfo()); } -
重启项目，访问测试 http://localhost:8080/swagger-ui.html 看下效果；
四、配置扫描接口
-
构建Docket时通过select()方法配置怎么扫描接口。
@Bean public Docket docket() { return new Docket(DocumentationType.SWAGGER_2) .apiInfo(apiInfo()) .select()// 通过.select()方法，去配置扫描接口,RequestHandlerSelectors配置如何扫描接口 .apis(RequestHandlerSelectors.basePackage("com.liming.controller")) .build(); } -
重启项目测试，由于我们配置根据包的路径扫描接口，所以我们只能看到一个类
-
除了通过包路径配置扫描接口外，还可以通过配置其他方式扫描接口，这里注释一下所有的配置方式：
1、
basePackage(final String basePackage)// 根据包路径扫描接口
2、any()// 扫描所有，项目中的所有接口都会被扫描到
3、none()// 不扫描接口4、// 通过方法上的注解扫描，如withMethodAnnotation(GetMapping.class)只扫描get请求
withMethodAnnotation(final Class<? extends Annotation> annotation)
5、// 通过类上的注解扫描，如.withClassAnnotation(Controller.class)只扫描有controller注解的类中的接口
withClassAnnotation(final Class<? extends Annotation> annotation) -
除此之外，我们还可以配置接口扫描过滤：
@Bean public Docket docket() { return new Docket(DocumentationType.SWAGGER_2) .apiInfo(apiInfo()) .select() .apis(RequestHandlerSelectors.basePackage("com.kuang.swagger.controller")) // 配置如何通过path过滤,即这里只扫描请求以/user开头的接口 .paths(PathSelectors.ant("/user/**")) .build(); } -
这里的可选值还有
any()// 任何请求都扫描
none()// 任何请求都不扫描
regex(final String pathRegex)// 通过正则表达式控制
ant(final String antPattern)// 通过ant()控制
SwaggerConfig基础配置全代码
package com.liming.config;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.web.servlet.config.annotation.ResourceHandlerRegistry;
import org.springframework.web.servlet.config.annotation.WebMvcConfigurationSupport;
import springfox.documentation.builders.ApiInfoBuilder;
import springfox.documentation.builders.PathSelectors;
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;
@Configuration
@EnableSwagger2// 开启Swagger2的自动配置
public class SwaggerConfig extends WebMvcConfigurationSupport {
@Bean //配置docket以配置Swagger具体参数
public Docket docket() {
return new Docket(DocumentationType.SWAGGER_2)
.apiInfo(apiInfo())
.select()
.apis(RequestHandlerSelectors.basePackage("com.limjing.controller")) // 只扫描controller接口
.paths(PathSelectors.any()) // 配置如何通过path过滤,即这里扫描所有请求的接口
.build();
}
//配置文档信息
private ApiInfo apiInfo() {
return new ApiInfoBuilder()
.title("Swagger标题") // 标题
.description("学习演示如何配置Swagger") //描述
.version("v1.0") // 版本
.contact(new Contact("黎明", "https://blog.csdn.net/weixin_46370595?type=blog", "2356731504@qq.com"))
.build();
}
/**
* 解决高版本springboot无法访问http://localhost:8001/swagger-ui.html
*
* @param registry void
*/
@Override
protected void addResourceHandlers(ResourceHandlerRegistry registry) {
// 解决静态资源无法访问
registry.addResourceHandler("/**").addResourceLocations("classpath:/static/");
// 解决swagger无法访问
registry.addResourceHandler("/swagger-ui.html").addResourceLocations("classpath:/META-INF/resources/");
// 解决swagger的js文件无法访问
registry.addResourceHandler("/webjars/**").addResourceLocations("classpath:/META-INF/resources/webjars/");
}
}
五、配置Swagger开关
-
通过enable()方法配置是否启用swagger，如果是false，swagger将不能在浏览器中访问了
@Bean public Docket docket() { return new Docket(DocumentationType.SWAGGER_2) .apiInfo(apiInfo()) .enable(false) //配置是否启用Swagger，如果是false，在浏览器将无法访问 .select() .apis(RequestHandlerSelectors.basePackage("nuc.ss.swagger.controller")) .paths(PathSelectors.ant("/ss/**")) .build(); }
-
如何动态配置当项目处于test、dev环境时显示swagger，处于prod时不显示？
@Bean public Docket docket(Environment environment) { // 设置要显示swagger的环境 Profiles of = Profiles.of("dev", "test"); // 判断当前是否处于该环境 // 通过 enable() 接收此参数判断是否要显示 boolean flag = environment.acceptsProfiles(of); return new Docket(DocumentationType.SWAGGER_2) .apiInfo(apiInfo()) .enable(flag) .select() .apis(RequestHandlerSelectors.basePackage("com.liming.controller")) .paths(PathSelectors.ant("/user/**")) .build(); } -
可以在项目中增加配置文件
application.yml ->spring.profiles.active=dev
application-dev.yml ->端口：8081
application-pro.yml->端口：8082结果：pro正式环境会关闭swagger功能
六、配置API分组
-
如果没有配置分组，默认是default。通过groupName()方法即可配置分组：
@Bean public Docket docket(Environment environment) { return new Docket(DocumentationType.SWAGGER_2).apiInfo(apiInfo()) .groupName("黎明") // 配置分组 // 省略配置.... } -
重启项目查看分组
-
如何配置多个分组？配置多个分组只需要配置多个docket即可：
@Bean public Docket docket1(){ return new Docket(DocumentationType.SWAGGER_2).groupName("group1"); } @Bean public Docket docket2(){ return new Docket(DocumentationType.SWAGGER_2).groupName("group2"); } @Bean public Docket docket3(){ return new Docket(DocumentationType.SWAGGER_2).groupName("group3"); } -
重启项目查看即可
七、实体配置
-
新建一个实体类
//@Api("注释") @ApiModel("用户实体") public class User { @ApiModelProperty("用户名") private String username; @ApiModelProperty("密码") private String password; public String getUsername() { return username; } public void setUsername(String username) { this.username = username; } public String getPassword() { return password; } public void setPassword(String password) { this.password = password; } } -
只要这个实体在请求接口的返回值上（即使是泛型），都能映射到实体项中：
@RestController public class HelloController { // /error默认错误请求 @GetMapping("/hello") public String hello() { return "hello"; } //只要我们的接口中，返回值中存在实体类，他就会被扫描到Swagger中 @PostMapping("/user") public User user() { return new User(); } } -
重启查看测试
注：并不是因为@ApiModel这个注解让实体显示在这里了，而是只要出现在接口方法的返回值上的实体都会显示在这里，而@ApiModel和@ApiModelProperty这两个注解只是为实体添加注释的.
-
@ApiModel为类添加注释
-
@ApiModelProperty为类属性添加注释
【注意点】：在正式发布的时候，关闭Swagger！！！
常用注解
Swagger的所有注解定义在io.swagger.annotations包下
下面列一些经常用到的，未列举出来的可以另行查阅说明：
| Swagger注解 | 简单说明 |
|---|---|
| @Api(tags = “xxxController说明”) | 作用在接口类上 |
| @ApiOperation(“xxx接口说明”) | 作用在接口方法上 |
| @ApiModel(“xxxPOJO说明”) | 作用在模型类上：如VO、BO |
| @ApiModelProperty(value = “xxx属性说明”,hidden = true) | 作用在类方法和属性上，hidden设置为true可以隐藏该属性 |
| @ApiParam(“xxx参数说明”) | 作用在参数、方法和字段上，类似@ApiModelProperty |
| @ApiImplicitParam() | 用于描述API接口的参数信息(常用的属性包括：name：参数名,value：参数的描述信息,paramType：参数的类型，可以是path、query、body、header、form等,dataType：参数的数据类型,required：参数是否必需，布尔值，默认为false,defaultValue：参数的默认值 |
我们也可以给请求的接口配置一些注释
-
在HelloController控制类中的接口添加api接口注释
@RestController public class HelloController { ...... @ApiOperation("Hello控制接口") @GetMapping("/hello") public String hello2(@ApiParam("用户名") String username) { return "hello" + username; } @ApiOperation("get测试") @GetMapping("/get") public User hello2(@ApiParam("用户") User user) { return user; } @GetMapping("/users/{id}") @ApiOperation(value = "获取用户详情") @ApiImplicitParam(name = "id", value = "用户ID", paramType = "path", dataType = "Long", required = true) public User getUserById(@PathVariable("id") Long id) { // 获取用户详情的业务逻辑 } @GetMapping("/users") @ApiOperation(value = "获取用户列表") @ApiImplicitParams({ @ApiImplicitParam(name = "page", value = "页码", paramType = "query", dataType = "int", defaultValue = "1"), @ApiImplicitParam(name = "size", value = "每页数量", paramType = "query", dataType = "int", defaultValue = "10") }) public List<User> getUsers(@RequestParam(defaultValue = "1") int page, @RequestParam(defaultValue = "10") int size) { // 获取用户列表的业务逻辑 } }
-
进行
try it out测试
测试结果
拓展：其他皮肤
我们可以导入不同的包实现不同的皮肤定义：
1、默认的 访问 http://localhost:8080/swagger-ui.html
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger-ui</artifactId>
<version>2.9.2</version>
</dependency>
2、bootstrap-ui 访问 http://localhost:8080/doc.html
<!--swaggerconfig解决高版本那里要换成doc.html-->
<!-- 引入swagger-bootstrap-ui包 /doc.html-->
<dependency>
<groupId>com.github.xiaoymin</groupId>
<artifactId>swagger-bootstrap-ui</artifactId>
<version>1.9.1</version>
</dependency>
八.微服务使用Knife4j
官网地址:https://doc.xiaominfo.com/
第一步：创建Spring Boot项目并且在pom.xml中引入Knife4j的依赖包，代码如下：
<dependency>
<groupId>com.github.xiaoymin</groupId>
<artifactId>knife4j-openapi2-spring-boot-starter</artifactId>
<version>4.3.0</version>
</dependency>
第二步：配置yml属性，代码如下：
knife4j:
enable: true #表示启用Knife4j，允许API文档生成和展示
openapi: #表示配置OpenAPI相关的信息
title: Knife4j官方文档 #设置了API文档的标题
description: "`我是测试`,**你知道吗** #设置了API文档的描述
email: 2356731504@qq.com #电子邮件地址
concat: 黎明 #联系人的名称
version: v1.0
license: Apache 2.0 #API使用的许可证为"Apache 2.0"
license-url: https://stackoverflow.com/ #提供了许可证的URL链接
terms-of-service-url: https://stackoverflow.com/ #提供了服务条款的URL链接
group: #分组信息
default:
group-name: default #分组名称
api-rule: package #按照包来进行API的分组
api-rule-resources: #指定了API规则的资源信息
- com.liming.controller
第三步:新建一个接口Controller类，如下：
@Api(tags = "首页模块")
@RestController
public class IndexController {
@ApiImplicitParam(name = "name",value = "姓名",required = true)
@ApiOperation(value = "向客人问好")
@GetMapping("/sayHi")
public ResponseEntity<String> sayHi(@RequestParam(value = "name")String name){
return ResponseEntity.ok("Hi:"+name);
}
}
万事俱备，启动Spring Boot项目，浏览器访问Knife4j的文档地址即可查看效果
http://ip:端口/doc.html
946
被折叠的 条评论
为什么被折叠?
到【灌水乐园】发言
