一步步学习java后台（六）(OpenApi-Swagger的使
OpenApi(Swagger)
OpenApi，以前称为Swagger ，是最受欢迎的API文档规范之一。
它允许您使用JSON或YAML元数据描述API的属性。它还提供了一个Web UI，它可以将元数据转换为一个很好的HTML文档。
SpringFox
SpringFox提供了自动生成Swagger-UI的组件。它可以自动检查您的类，检测控制器，它们的方法，它们使用的模型类以及它们映射到的URL。没有任何手写文档，只需检查应用程序中的类，它就可以生成大量有关API的信息。
在Spring Boot工程中添加 Swagger2
springfox-swagger2 2.x.x版本
1.在pom文件中添加Swagger2依赖
<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>
- 创建Swagger2配置类
在在Application.java同级创建Swagger2的配置类Swagger2。
image.png
@Configuration
@EnableSwagger2
public class Swagger2 {
@Bean
public Docket createRestApi() {
return new Docket(DocumentationType.SWAGGER_2)
.apiInfo(apiInfo())
.select()
.paths(PathSelectors.any())
.build();
}
private ApiInfo apiInfo() {
return new ApiInfoBuilder()
.title("Spring Boot 初始化学习工程")
.version("1.0")
.build();
}
}
通过@Configuration注解，让Spring来加载该类配置。再通过@EnableSwagger2注解来启用Swagger2。
再通过createRestApi函数创建Docket的Bean之后，apiInfo()用来创建该Api的基本信息（这些基本信息会展现在文档页面中）。select()函数返回一个ApiSelectorBuilder实例用来控制哪些接口暴露给Swagger来展现，本例采用指定扫描的包路径来定义，Swagger会扫描该包下所有Controller定义的API，并产生文档内容（除了被@ApiIgnore指定的请求）。
访问如下地址就可以访问 Swagger
http://localhost:8080/swagger-ui.html#/
git地址：
tag: 1-swaggur-2.x
springfox 3.x.x版本
2020年6月 Springfox 发布了3.0.0版本，进一步简化了配置。
.在pom文件中添加OpenApi启动器
<groupId>io.springfox</groupId>
<artifactId>springfox-boot-starter</artifactId>
<version>3.0.0</version>
</dependency>
在Application上添加注解
@EnableOpenApi
image.png
配置类可加可不加
访问地址变更为：
http://localhost:8080/swagger-ui/index.html#/
OpenApi注解
image.png
虽然不加任何注解，生成的UI页面也可以提供接口，参数等等信息，但是我们还是希望可以获取更加人性化的提示。通过注解 @ApiOperation，@ApiImplicitParam就可以做到。
@ApiOperation(value="创建用户", notes="根据User对象创建用户")
@PostMapping("/")
public String postUser(@RequestBody User user) {
// @RequestBody注解用来绑定通过http请求中application/json类型上传的数据
users.put(user.getId(), user);
return "success";
}
@ApiOperation(value="获取用户详细信息", notes="根据url的id来获取用户详细信息")
@ApiImplicitParam(name = "id", value = "用户ID", required = true, dataType = "Long", example = "0")
@GetMapping("/{id}")
public User getUser(@PathVariable Long id) {
// url中的id可通过@PathVariable绑定到函数的参数中
return users.get(id);
}
image.png
遇到的报错
- 工程无法运行起来
报错：
Parameter 0 of method linkDiscoverers in org.springframework.hateoas.config.HateoasConfiguration required a single bean, but 15 were found:
资料1中使用的pom maven版本号为 2.0.2 导致
- 打开Swagger页面时报错
java.lang.NumberFormatException: For input string: ""
新版Swagger需要赋值，而且类型需要和dataType相符
image.png
参考资料：
1）Spring Boot中使用Swagger2构建强大的RESTful API文档 （推荐，主要是参考这篇写的）
2）[Spring Boot - Enabling Swagger2] (https://www.tutorialspoint.com/spring_boot/spring_boot_enabling_swagger2.htm)
3） [SpringFox的更新记录] （http://springfox.github.io/springfox/docs/current/#changes-in-swagger-ui）
4）[SpringFox 3.0 升级指南] https://blog.csdn.net/qq_15973399/article/details/107436089
