0
点赞
收藏
分享

微信扫一扫

【第十三篇】Spring Boot集成 Swagger2 展现在线接口文档

Java架构领域 2022-03-13 阅读 56
spring bootjavaspringSwagger2在线接口文档

1.1 Swagger 简介

1.1.1 解决的问题

随着互联网技术的发展，现在的网站架构基本都由原来的后端渲染，变成了前后端分离的形态，而且前端技术和后端技术在各自的道路上越走越远。前端和后端的唯一联系，变成了API 接口，所以API 文档变成了前后端开发人员联系的纽带，变得越来越重要。

那么问题来了，随着代码的不断更新，开发人员在开发新的接口或者更新旧的接口后，由于开发任务的繁重，往往文档很难持续跟着更新，Swagger就是用来解决该问题的一款重要的工具，对使用接口的人来说，开发人员不需要给他们提供文档，只要告诉他们一个 Swagger 地址，即可展示在线的API接口文档，除此之外，调用接口的人员还可以在线测试接口数据，同样地，开发人员在开发接口时，同样也可以利用 Swagger在线接口文档测试接口数据，这给开发人员提供了便利。

1.1.2 Swagger官方

我们打开 Swagger官网，官方对 Swagger的定义为：

翻译成中文是：“最好的 API是使用 Swagger工具构建的”。由此可见，Swagger官方对其功能和所处的地位非常自信，由于其非常好用，所以官方对其定位也合情合理。如下图所示：
在这里插入图片描述
本文主要讲解在Spring Boot中如何导入Swagger2工具来展现项目中的接口文档。本节课使用的 Swagger版本为2.2.2。

1.2 Swagger2的 maven 依赖

使用 Swagger2工具，必须要导入maven依赖，当前官方最高版本是 2.8.0，我尝试了一下，个人感觉页面展示的效果不太好，而且不够紧凑，不利于操作。另外，最新版本并不一定是最稳定版本，当前我们实际项目中使用的是2.2.2 版本，该版本稳定，界面友好，所以本节课主要围绕着 2.2.2版本来展开，依赖如下：

<dependency>
	<groupId>io.springfox</groupId>
	<artifactId>springfox-swagger2</artifactId>
	<version>2.2.2</version>
</dependency>
<dependency>
	<groupId>io.springfox</groupId>
	<artifactId>springfox-swagger-ui</artifactId>
	<version>2.2.2</version>
</dependency>

1.3 Swagger2的配置

使用 Swagger2 需要进行配置，Spring Boot 中对Swagger2 的配置非常方便，新建一个配置类，Swagger2 的配置类上除了添加必要的 @Configuration注解外，还需要添加 @EnableSwagger2注解。

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;

@Configuration
@EnableSwagger2
public class SwaggerConfig {

 
   @Bean //配置docket以配置Swagger具体参数
    public Docket createRestApi(Environment environment) {
		     // 设置要显示swagger的环境
		     Profiles of = Profiles.of("dev", "test");
		     // 判断当前是否处于该环境
		     // 通过 enable() 接收此参数判断是否要显示
		     boolean b = environment.acceptsProfiles(of);


        return new Docket(DocumentationType.SWAGGER_2)
                // 指定构建api文档的详细信息的方法：apiInfo()
                .apiInfo(apiInfo())
                .enable(b) //配置是否启用Swagger，如果是false，在浏览器将无法访问
                .select()
                // 指定要生成api接口的包路径，这里把controller作为包路径，生成controller中的所有接口
                .apis(RequestHandlerSelectors.basePackage("com.itcodai.course06.controller"))
                 // 配置如何通过path过滤,即这里只扫描请求以/kuang开头的接口
                 // .paths(PathSelectors.ant("/kuang/**"))
                .paths(PathSelectors.any())
                .build();
    }

    /**
     * 构建api文档的详细信息
     * @return
     */
    private ApiInfo apiInfo() {
      Contact contact = new Contact("联系人名字", "http://xxx.xxx.com/联系人访问链接", "联系人邮箱");
   return new ApiInfo(
           "Swagger学习", // 标题
           "学习演示如何配置Swagger", // 描述
           "v1.0", // 版本
           "http://terms.service.url/组织链接", // 组织链接
           contact, // 联系人信息
           "Apach 2.0 许可", // 许可
           "许可链接", // 许可连接
           new ArrayList<>()// 扩展
  );
}

在该配置类中，已经使用注释详细解释了每个方法的作用了，在此不再赘述。到此为止，我们已经配置好了 Swagger2 了。现在我们可以测试一下配置有没有生效，启动项目，在浏览器中输入 localhost:8080/swagger-ui.html，即可看到 swagger2 的接口页面，如下图所示，说明Swagger2集成成功。
在这里插入图片描述
结合该图，对照上面的Swagger2 配置文件中的配置，可以很明确的知道配置类中每个方法的作用。这样就很容易理解和掌握Swagger2 中的配置了，也可以看出，其实 Swagger2配置很简单。

1.4 Swagger2 的使用

上面我们已经配置好了 Swagger2，并且也启动测试了一下，功能正常，下面我们开始使用Swagger2，主要来介绍 Swagger2 中的几个常用的注解，分别在实体类上、 Controller 类上以及Controller中的方法上，最后我们看一下 Swagger2是如何在页面上呈现在线接口文档的，并且结合 Controller中的方法在接口中测试一下数据。

1.4.1 实体类注解

本节我们建一个 User实体类，主要介绍一下Swagger2中的@ApiModel和@ApiModelProperty 注解，同时为后面的测试做准备。

import io.swagger.annotations.ApiModel;
import io.swagger.annotations.ApiModelProperty;

@ApiModel(value = "用户实体类")
public class User {
    @ApiModelProperty(value = "用户唯一标识")
    private Long id;
    @ApiModelProperty(value = "用户姓名")
    private String username;
    @ApiModelProperty(value = "用户密码")
    private String password;
	// 省略set和get方法
}

解释下 @ApiModel 和 @ApiModelProperty 注解：

该注解在在线API文档中的具体效果在下文说明。

1.4.2 Controller 类中相关注解

我们写一个 TestController，再写几个接口，然后学习一下 Controller中和 Swagger2相关的注解。

import com.itcodai.course06.entiy.JsonResult;
import com.itcodai.course06.entiy.User;
import io.swagger.annotations.Api;
import io.swagger.annotations.ApiOperation;
import io.swagger.annotations.ApiParam;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.PathVariable;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RestController;

@RestController
@RequestMapping("/swagger")
@Api(value = "Swagger2 在线接口文档")
public class TestController {

    @GetMapping("/get/{id}")
    @ApiOperation(value = "根据用户唯一标识获取用户信息")
    public JsonResult<User> getUserInfo(@PathVariable @ApiParam(value = "用户唯一标识") Long id) {
        // 模拟数据库中根据id获取User信息
        User user = new User(id, "倪升武", "123456");
        return new JsonResult(user);
    }
}

我们来学习一下 @Api 、 @ApiOperation 和@ApiParam注解。

这里返回的是 JsonResult，是下一节课我们要学习的如何统一封装返回json 数据时的实体。以上是Swagger中最常用的 5 个注解，接下来运行一下项目工程，在浏览器中输入 localhost:8080/swagger-ui.html看一下 Swagger页面的接口状态。
在这里插入图片描述
可以看出，Swagger 页面对该接口的信息展示的非常全面，每个注解的作用以及展示的地方在上图中已经标明，通过页面即可知道该接口的所有信息，那么我们直接在线测试一下该接口返回的信息，输入id为1，看一下返回数据：
在这里插入图片描述
可以看出，直接在页面返回了json格式的数据，开发人员可以直接使用该在线接口来测试数据的正确与否，非常方便。上面是对于单个参数的输入，如果输入参数为某个对象这种情况，Swagger是什么样子呢？我们再写一个接口。

@PostMapping("/insert")
    @ApiOperation(value = "添加用户信息")
    public JsonResult<Void> insertUser(@RequestBody @ApiParam(value = "用户信息") User user) {
        // 处理添加逻辑
        return new JsonResult<>();
    }

重启项目，在浏览器中输入localhost:8080/swagger-ui.html看一下效果：
在这里插入图片描述

1.5 其他皮肤

我们可以导入不同的包实现不同的皮肤定义：

1.5.1 默认的访问 http://localhost:8080/swagger-ui.html

<dependency>
   <groupId>io.springfox</groupId>
   <artifactId>springfox-swagger-ui</artifactId>
   <version>2.9.2</version>
</dependency>

在这里插入图片描述

1.5.2 bootstrap-ui 访问 http://localhost:8080/doc.html

<!-- 引入swagger-bootstrap-ui包 /doc.html-->
<dependency>
   <groupId>com.github.xiaoymin</groupId>
   <artifactId>swagger-bootstrap-ui</artifactId>
   <version>1.9.1</version>
</dependency>

在这里插入图片描述

1.5.3 Layui-ui 访问http://localhost:8080/docs.html

<!-- 引入swagger-ui-layer包 /docs.html-->
<dependency>
   <groupId>com.github.caspar-chen</groupId>
   <artifactId>swagger-ui-layer</artifactId>
   <version>1.1.3</version>
</dependency>

在这里插入图片描述

1.5.4 mg-ui 访问http://localhost:8080/document.html

<!-- 引入swagger-ui-layer包 /document.html-->
<dependency>
   <groupId>com.zyplayer</groupId>
   <artifactId>swagger-mg-ui</artifactId>
   <version>1.0.6</version>
</dependency>

在这里插入图片描述

1.6 总结

OK，本节课详细分析了Swagger的优点，以及Spring Boot如何集成Swagger2，包括配置，相关注解的讲解，涉及到了实体类和接口类，以及如何使用。最后通过页面测试，体验了Swagger的强大之处，基本上是每个项目组中必备的工具之一，所以要掌握该工具的使用。

相较于传统的Postman或Curl方式测试接口，使用swagger简直就是傻瓜式操作，不需要额外说明文档(写得好本身就是文档)而且更不容易出错，只需要录入数据然后点击Execute，如果再配合自动化框架，可以说基本就不需要人为操作了。

Swagger是个优秀的工具，现在国内已经有很多的中小型互联网公司都在使用它，相较于传统的要先出Word接口文档再测试的方式，显然这样也更符合现在的快速迭代开发行情。当然了，提醒下大家在正式环境要记得关闭Swagger，一来出于安全考虑二来也可以节省运行时内存。

举报

相关推荐

【swagger2】Spring Boot 配置swagger2

spring bootjavaspring

Spring Boot 集成 Swagger2，构建强大的 API 文档

javaspring bootswagger2后端spring

Swagger2接口文档

elementui蓝桥杯postman

Spring Boot整合Swagger2 Swagger2配置

spring bootspringjava

Spring Boot 集成 Swagger 构建接口文档

随笔spingboot后端技术栈

Springboot整合Swagger2在线文档

springUserciJava编程语言yyds干货盘点

Spring Boot整合Swagger2

SpringBootspringspringbootSpringB...JavaWeb技术

spring boot学习第十三篇:使用jsonrpc

gitelasticsearch大数据

springboot整合swagger2接口文档

spring bootjavaspring

接口文档swagger2的使用

phpweb安全安全
0 条评论