SpringBoot整合SwaggerUI实现在线 API文档-京东云开发者社区

### 1 背景

现在项目开发过程中，大部分是前后端分离开发，网站和移动端都需要进行数据交互和对接，前后端开发人员在协作开发时，需要交流共同维护一个接口文档，如果能有一个规范的标准的API文档，就能够大大减少沟通成本，进行高效的协作开发。

### 2 SwaggerUI介绍

Swagger UI是一款RESTFUL接口的文档在线自动生成+功能测试功能软件。

基于html+javascript实现，倾向于在线文档和测试，使用和集成十分简单，能容易地生成不同模块下的API列表， 每个API接口描述和参数、请求方法都能定制并直接测试得到直观的响应数据。

##### 常用注解

- @Api()用于类； 表示标识这个类是swagger的资源
- @ApiOperation()用于方法； 表示一个http请求的操作
- @ApiParam()用于方法，参数，字段说明； 表示对参数的添加元数据（说明或是否必填等）
- @ApiModel()用于类 表示对类进行说明，用于参数用实体类接收
- @ApiModelProperty()用于方法，字段 表示对model属性的说明或者数据操作更改
- @ApiIgnore()用于类，方法，方法参数 表示这个方法或者类被忽略@ApiImplicitParam() 用于方法 表示单独的请求参数@ApiImplicitParams() 用于方法，包含多个 @ApiImplicitParam

详情可以查看官网:https://swagger.io/tools/swagger-ui/

### 3 SpringBoot整合Swagger-ui过程

在这里下载一个项目https://start.spring.io/ 也可以在idea新建SpringBoot-Web工程.

![](//img1.jcloudcs.com/developer.jdcloud.com/66241fd2-2126-4708-9514-24177d3c4a2720220207144637.png)

#### 3.1 在项目的pom.xml文件中添加项目依赖

在pom.xml文件中添加SwaggerUI依赖,导入springfox-swagger2和springfox-swagger-ui

```xml

<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>
```

![](//img1.jcloudcs.com/developer.jdcloud.com/71352c8d-0cfe-4b80-b988-b9230c68167220220207144719.png)

#### 3.2 在项目中增加一个SwaggerConfig.java配置类,将对象注入到spring中

```java
/**
     * 配置了Swagger 的Docket的bean实例,扫描接口的位置
     * .apis
     *   RequestHandlerSelectors 配置swagger扫描接口的方式
     *      basePackage() 指定要扫描哪些包
     *      any() 全部都扫描
     *      none() 全部不扫描
     *      withClassAnnotation() 扫描类上的注解 参数是一个注解的反射对象
     *      withMethodAnnotation() 扫描包上的注解
     * .paths
     *   PathSelectors 路径扫描接口
     * @return
     */
@Configuration
@EnableSwagger2
public class SwaggerConfig {
    @Bean
    public Docket createRestApi() {
        return new Docket(DocumentationType.SWAGGER_2)
                .pathMapping("/")
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.jenk.recative.controller"))//指定包下生成API文档
                .paths(PathSelectors.any())
                .build().apiInfo(new ApiInfoBuilder()
                        .title("SpringBoot 整合 Swagger2 构建RESTFUL APIS")
                        .description("SpringBoot整合Swagger2，详细信息......")
                        .version("2.0")
                        .license("JDL攻城狮联盟")
                        .licenseUrl("http://jnews.jd.com/circle-info?id=41")
                        .build());
    }
}
```

#### 3.3 新增Product实体类，加上Swagger相关注解，@ApiModel ， @ApiModelProperty

![](//img1.jcloudcs.com/developer.jdcloud.com/11cbb218-76d2-4585-9731-e3d036aca45620220207144759.png)

#### 3.4 此时可以启动项目查看一下，效果如下，可以看到我们写的Swagger-ui页面可以正常访问了

![](//img1.jcloudcs.com/developer.jdcloud.com/9c0f03c4-3f27-482c-956b-2858a3d62a7a20220207150322.png)

#### 3.5 还没有正常的API接口生成，我们需要编写代码

写一个Productcontroller.java ，写几个接口进行发布测试。Swagger2相关的注解其实并不多，而且很容易懂。

@Api注解可以用来标记当前Controller的功能。
@ApiOperation注解用来标记一个方法的作用。
@ApiImplicitParam注解用来描述一个参数，可以配置参数的中文含义，也可以给参数设置默认值，这样在接口测试的时候可以避免手动输入。

如果有多个参数，则需要使用多个@ApiImplicitParam注解来描述，多个@ApiImplicitParam注解需要放在一个@ApiImplicitParams注解中。

需要注意的是，@ApiImplicitParam注解中虽然可以指定参数是必填的，但是却不能代替@RequestParam(required = true)，前者的必填只是在Swagger2框架内必填，抛弃了Swagger2，这个限制就没用了，所以假如开发者需要指定一个参数必填，@RequestParam(required = true)注解还是不能省略。

![](//img1.jcloudcs.com/developer.jdcloud.com/da89a9ce-38e5-41a1-8d9e-a6375e8a788620220207150358.png)

![](//img1.jcloudcs.com/developer.jdcloud.com/09416fe4-d46a-4899-b55c-0c038edd43c320220207150411.png)

#### 3.6 再启动项目，查看一下效果

![](//img1.jcloudcs.com/developer.jdcloud.com/457e8b64-c6dd-480d-ba8f-38f46db410fe20220207151031.png)

我们已经可以看到有接口已经可以使用了。这时我们可以测试使用一下我们发布的接口。
点开可以查看发布的接口信息和实体类型信息

![](//img1.jcloudcs.com/developer.jdcloud.com/b36c8cc9-93ae-45a4-8d58-4ebb60b7bf0120220207151057.png)

接下来使用一下吧

![](//img1.jcloudcs.com/developer.jdcloud.com/2da2e02f-8f5a-422c-a13e-9c45ada9e36b20220207151109.png)

![](//img1.jcloudcs.com/developer.jdcloud.com/3108faea-4201-43d5-9b49-98239d3667a820220207151121.png)

![](//img1.jcloudcs.com/developer.jdcloud.com/963ecb81-6b1c-4297-8237-06b533d33e3120220207151128.png)

![](//img1.jcloudcs.com/developer.jdcloud.com/b16bcda5-35a0-4161-a949-5d8e8e6eac6520220207151141.png)

![](//img1.jcloudcs.com/developer.jdcloud.com/43d75779-f9f1-424a-9ae8-a51d37fa756420220207151146.png)

![](//img1.jcloudcs.com/developer.jdcloud.com/c874bf09-17fa-4ec3-ae3c-2cbd64b5a78420220207151153.png)

通过以上的步骤，就可以实现Swagger-ui的整合使用，自己测试或者和别人联合开发就不用写接口文档了，会使用这个之后，前端小伙伴和使用接口的小伙伴可以轻松的使用了。

为了避免我们开发过程中接口或者环境冲突，我们还可以自定义API分组

#### 3.7 配置 API分组

创建两个properties文件
application.properties 生产环境

![](//img1.jcloudcs.com/developer.jdcloud.com/e2fe4b7b-4ee2-4c0a-a399-a590bbf0729e20220207152004.png)

application-dev.properties 开发环境

![](//img1.jcloudcs.com/developer.jdcloud.com/91d22637-5d6f-4c8a-bc99-93c029866e1020220207152016.png)

在协同开发时，每个开发人员都拥有一个属于自己的API组
编写多个Docket 设置不同Docket方法名

![](//img1.jcloudcs.com/developer.jdcloud.com/5455a057-c453-490e-a2cc-e5cf5750211a20220207152030.png)

![](//img1.jcloudcs.com/developer.jdcloud.com/0d2f98b9-3213-48f5-8209-2c62921f6d0a20220207152044.png)

这时就可以使用自己的分组进行发布API，互不影响了，其他细节和功能，小伙伴们可以在实战过程中进行整合使用。

### 4 总结

以上是springboot 整合SwaggerUI的全过程，通过上述结果可以看出来，不仅构建出一个简单的在线API文档和功能测试的工具，同时也方便了前后端开发及调用接口的小伙伴，充分高效的协作开发。解决了我们编写接口文档的痛点。

SwaggerUI的更多学习可以参考官网 ： https://swagger.io/tools/swagger-ui/

------------

###### 自猿其说Tech-京东物流技术发展部
###### 作者：李岩科