一、什么是Swagger
由于Spring Boot能够快速开发、便捷部署等特性，相信有很大一部分Spring Boot的用户会用来构建RESTful API。由于存在多终端的情况（移动端，web前端，小程序等），所以我们会抽象出RESTful API并共用一些底层业务代码。
由于接口众多，并且细节复杂，所以催生了一些api框架，Swagger就凭借其使用简单、实时更新等特点脱颖而出。Swagger可以轻松的整合到Spring Boot中，并与Spring MVC程序配合组织出强大RESTful API文档。它既可以减少我们创建文档的工作量，同时说明内容又整合入实现代码中，让维护文档和修改代码整合为一体，可以让我们在修改代码逻辑的同时方便的修改文档说明。另外Swagger2也提供了强大的页面测试功能来调试每个RESTful API。
使用SwaggerHub，您可以：
以OpenAPI格式定义您的API。
将所有API定义托管在一个地方。
将常见的API组件（例如数据模型和响应）存储在域中，并从API定义中引用它们。
与您的团队就API定义进行协作。
生成服务器和客户端代码，并将其推送到GitHub，GitLab，Bitbucket或Azure DevOps Services。
公开和私下共享您的API。
迭代API设计并管理多个API 版本。
二、在SpringBoot中使用Swagger
2.1 在pom中添加swagger的依赖
要使用swagge，我们首先需要在项目的pom中添加swagger依赖（这里使用的是maven构建，如果是gradle请在build.gradle中添加）。我们需要添加的依赖主要有两个，分别是swagger和swagger-ui，如果要使用其他功能(如接口文档导出)还需要引入对应的包。
<!--swagger API获取-->
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger2</artifactId>
<version>2.9.2</version>
</dependency>
<!--swagger-ui API获取-->
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger-ui</artifactId>
<version>2.9.2</version>
</dependency>2.2 添加swagger配置类
创建SwaggerConfig.java类
package com.oycbest.springbootswagger.config;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import springfox.documentation.builders.ApiInfoBuilder;
import springfox.documentation.builders.PathSelectors;
import springfox.documentation.builders.RequestHandlerSelectors;
import springfox.documentation.service.ApiInfo;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2;
/**
* @Description: swagger 配置类
* @Author oyc
* @Date 2020/5/5 3:47 下午
*/
@Configuration
@EnableSwagger2
public class SwaggerConfig {
/**
* 创建API
*/
@Bean
public Docket createRestApi() {
// 指定扫描包路径
return new Docket(DocumentationType.SWAGGER_2) // 指定生成的文档的类型是Swagger2
// .pathMapping("/swagger")
// 用来创建该API的基本信息，展示在文档的页面中（自定义展示的信息）,配置文档页面的基本信息内容
// 设置哪些接口暴露给Swagger展示
.select()
// 扫描所有有注解的api，用这种方式更灵活
//.apis(RequestHandlerSelectors.withMethodAnnotation(ApiOperation.class))
.apis(RequestHandlerSelectors.basePackage("com.oycbest.springbootswagger.controller"))
// 扫描所有 .apis(RequestHandlerSelectors.any())
.paths(PathSelectors.any()).build();
}
/**
* 添加摘要信息
*/
private ApiInfo apiInfo() {
// 用ApiInfoBuilder进行定制
return new ApiInfoBuilder()
// 设置标题
.title("描述：Spring Boot中使用Swagger2构建RESTful APIs")
// 描述
.description("swagger 测试demo")
//作者信息、联系方式：Contact(String name, String url, String email)
.contact(new Contact("oyc","https://blog.csdn.net/u014553029","1456682842@qq.com"))
// 版本
.version("版本号: 1.0.1")
.build();
}
}
- @Configuration 配置类，启动时加载此类
- @EnabledSwagger2 标识项目启动 SwaggerApi 文档
- ApiInfo 这个类时Swagger 页面展示的一些基础信息
- RequestHandlerSelectors.basePackage("com.oycbest.springbootswagger.controller“) 这里的com.oycbest.springbootswagger.controller是扫描包的路径
2.3 在controller中添加swagger接口注解
package com.oycbest.springbootswagger.controller;
import io.swagger.annotations.Api;
import io.swagger.annotations.ApiOperation;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RestController;
/**
* @Description: 测试swagger controller
* @Author oyc
* @Date 2020/5/5 3:43 下午
*/
@RestController
@Api(tags = "SwaggerController", description = "SwaggerController | 测试swagger")
@RequestMapping("api")
public class SwaggerController {
@GetMapping("hello")
@ApiOperation(value="hello 方法", notes="hello Swagger测试方法--hello")
public String hello(){
return "hello";
}
@GetMapping("test1")
@ApiOperation(value="test1 方法", notes="hello Swagger测试方法--test1")
public String test1(){
return "test1";
}
@GetMapping("test2")
@ApiOperation(value="test2 方法", notes="hello Swagger测试方法-test2")
public String test2(){
return "test2";
}
}
- @Api 修饰整个类，描述Controller的作用。
- @ApiOperation 修饰一个类的一个方法，或者说一个接口 ，可以描述这个方法的功能和注意事项。若不使用则用函数名作为方法功能。
参数：value="说明方法的用途、作用"
notes="方法的备注说明"
- @apiResponses：用在请求的方法上，表示一组响应
- @ApiResponse：用在@ApiResponses中，一般用于表达一个错误的响应信息
code：数字，例如400
message：信息，例如"请求参数没填好"
response：抛出异常的类
- @ApiImplicitParams 修饰方法，可以描述这个方法的参数的作用。若不使用则用参数名作为参数的作用。
- @ApiImplicitParam：用在@ApiImplicitParams注解中，指定一个请求参数的各个方面
name：参数名
value：参数的汉字说明、解释
required：参数是否必须传
paramType：参数放在哪个地方
· header --> 请求参数的获取：@RequestHeader
· query --> 请求参数的获取：@RequestParam
· path（用于restful接口）--> 请求参数的获取：@PathVariable
· body（不常用）
· form（不常用）
dataType：参数类型，默认String，其它值dataType="Integer"
defaultValue：参数的默认值- @ApiModel 修饰实体类，可以描述这个类的功能。
- @ApiModelProperty 修饰实体类的属性，可以描述这个属性的作用。
- @ApiIgnore修饰参数、方法和类，可以在自动生成文档时对修饰的对象进行忽略。
- @ApiError ：发生错误返回的信息
2.4 查看&测试接口
如果没有引入安全框架或设置路径拦截机制，可以直接访问 http://127.0.0.1:8080/[项目名称]/swagger-ui.html查看接口。
接口列表：
测试接口：
三、集成knife4j进行在线接口调试
什么是knife4j？
knife4j是为
Java MVC框架集成Swagger生成Api文档的增强解决方案,前身是swagger-bootstrap-ui,具有小巧,轻量,并且功能强悍的优点。
Knife4j提供两大核心功能：文档说明 和 在线调试
- 文档说明：根据
Swagger的规范说明，详细列出接口文档的说明，包括接口地址、类型、请求示例、请求参数、响应示例、响应参数、响应码等信息，使用swagger-bootstrap-ui能根据该文档说明，对该接口的使用情况一目了然。- 在线调试：提供在线接口联调的强大功能，自动解析当前接口参数,同时包含表单验证，调用参数可返回接口响应内容、
headers、Curl请求命令实例、响应时间、响应状态码等信息，帮助开发者在线调试，而不必通过其他测试工具测试接口是否正确,简洁、强大。为什么要用knife4j?
在第二节，我们使用
Swagger来进行接口调试、前端提供接口文档，但是Swagger并没有实际上那么方便，比如我们在发送Post请求时，参数选填还是非常不友好，那么有没有更好的工具呢？那么，knife4j将是一个不错的选择。
使用knife4j:
3.1 注入依赖
<dependency>
<groupId>com.github.xiaoymin</groupId>
<artifactId>knife4j-spring-boot-starter</artifactId>
<version>2.0.4</version>
</dependency>3.2 在SwaggerConfig中添加注解：@EnableKnife4j
/**
* @Description: swagger 配置类
* @Author oyc
* @Date 2020/5/5 3:47 下午
*/
@Configuration
@EnableSwagger2
@EnableKnife4j
public class SwaggerConfig {
//省略部分代码
}
3.3 使用knife4j查看接口文档、进行接口测试
在浏览器中打开： http://127.0.0.1:8080/[项目名称]/doc.html
主界面：
接口描述界面：
测试接口：
源码地址：https://github.com/oycyqr/springboot-learning-demo/tree/master/springboot-swagger
扫一扫
1万+
被折叠的 条评论
为什么被折叠?
到【灌水乐园】发言
