一步步学习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>

2. 创建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

遇到的报错

1. 工程无法运行起来

报错：

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 导致

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