如何实现SpringBoot整合swagger-ui并实现分组展示API操作？

本文共计2015个文字，预计阅读时间需要9分钟。

大家好，本文将展示如何在Spring Boot项目中集成Swagger UI。虽然有人认为这些都是老生常谈，网上的例子也不算多，但实际上Swagger已经存在很长时间了。虽然如此，我在使用过程中遇到了一个问题，下面将具体说明。

在Spring Boot项目中集成Swagger UI通常涉及以下几个步骤：

1. 添加依赖：在`pom.xml`中添加Swagger的依赖。

2.配置Swagger：创建一个配置类来配置Swagger。

3.启动Swagger：确保Swagger的相关注解和配置在项目中正确应用。

以下是一个简单的示例：

java

// 添加Swagger依赖到pom.xml io.springfox springfox-swagger2 2.9.2 io.springfox springfox-swagger-ui 2.9.2

// 创建Swagger配置类@Configuration@EnableSwagger2public class SwaggerConfig { @Bean public Docket api() { return new Docket(DocumentationType.SWAGGER_2) .select() .apis(RequestHandlerSelectors.basePackage(com.example.project)) .paths(PathSelectors.any()) .build(); }}

在上述代码中，我们配置了Swagger来扫描`com.example.project`包下的所有API。

接下来，确保你的Controller或Service类使用了相应的Swagger注解，例如`@ApiOperation`和`@ApiParam`。

最后，启动Spring Boot应用后，访问`/swagger-ui.`即可查看Swagger UI界面。

如果在集成过程中遇到问题，以下是一些常见的问题和解决方案：

1. 问题：Swagger UI无法访问。 - 解决方案：检查配置类是否正确，确保`@EnableSwagger2`注解在配置类上，并且路径配置正确。

2. 问题：Swagger UI中API列表为空。 - 解决方案：确保你的Controller或Service类使用了Swagger注解，并且类和方法的访问权限允许被Swagger扫描。

3. 问题：Swagger UI中显示的参数与实际API不一致。 - 解决方案：检查你的API接口是否正确使用了Swagger注解，例如`@ApiParam`。

希望这个简单的指南能帮助你顺利地在Spring Boot项目中集成Swagger UI。

大家好，这篇文章展示下如何在springboot项目中集成swagger-ui。有人说，这都是老生常谈，网上的例子数不胜数。确实swagger诞生至今已经很久了，但是在使用过程中我遇到一个问题，下面给大家分享下我的使用心得吧。

1.swagger配置类

第一步，需要在pom中引入相应的配置，这里使用2.7.0的版本。需要注意的是2.7.0和2.8.0的版本在界面风格上差异很大，如果感兴趣，可以试试2.8.0以上的版本，我比较青睐使用2.7.0及以下的版本，因为界面比较清爽。

第一步 引入pom

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

第二步

在代码中加入相应的配置，新建config包，写入swaggerConfig配置类：

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.service.Contact; import springfox.documentation.spi.DocumentationType; import springfox.documentation.spring.web.plugins.Docket; import springfox.documentation.swagger2.annotations.EnableSwagger2; @Configuration @EnableSwagger2 public class SwaggerConfig { /** * 创建API应用 * apiInfo() 增加API相关信息 * 通过select()函数返回一个ApiSelectorBuilder实例,用来控制哪些接口暴露给Swagger来展现， * 本例采用指定扫描的包路径来定义指定要建立API的目录。 * * @return */ @Bean public Docket restApi() { return new Docket(DocumentationType.SWAGGER_2) .groupName("标准接口") .apiInfo(apiInfo("Spring Boot中使用Swagger2构建RESTful APIs", "1.0")) .useDefaultResponseMessages(true) .forCodeGeneration(false) .select() .apis(RequestHandlerSelectors.basePackage("com.xqnode.learning.controller")) .paths(PathSelectors.any()) .build(); } /** * 创建该API的基本信息（这些基本信息会展现在文档页面中） * 访问地址：ip:port/swagger-ui.html * * @return */ private ApiInfo apiInfo(String title, String version) { return new ApiInfoBuilder() .title(title) .description("更多请关注: jb51.net") .termsOfServiceUrl("jb51.net") .contact(new Contact("xqnode", "jb51.net", "xiaqingweb@163.com")) .version(version) .build(); } }

.apis(RequestHandlerSelectors.basePackage(“com.xqnode.learning.controller”))这个配置是用来指定我们的接口层的位置，大家可以根据你自己项目的实际情况来进行修改。.apiInfo()是定义一些我们项目的描述信息，可以根据实际需要在参数中修改。需要注意的是配置类的头部需要加上@Configuration，声明配置类，以及@EnableSwagger2加载swagger的一些相关配置。

2.使用swagger

我们在刚才指定的接口层使用swagger来说明接口的使用方法。

import com.fasterxml.jackson.databind.ObjectMapper; import io.swagger.annotations.Api; import io.swagger.annotations.ApiOperation; import io.swagger.annotations.ApiParam; import org.springframework.web.bind.annotation.PostMapping; import org.springframework.web.bind.annotation.RequestBody; import org.springframework.web.bind.annotation.RequestMapping; import org.springframework.web.bind.annotation.RestController; import javax.annotation.Resource; import java.io.IOException; import java.util.Map; @RestController @RequestMapping("/api") @Api(tags = "标准演示接口") public class ApiController { @Resource private ObjectMapper mapper; @PostMapping("/ps") @ApiOperation(value = "接受json参数", notes = "演示json参数是否接受成功") public String post(@ApiParam(name = "接收json参数", defaultValue = "{}") @RequestBody String json) throws IOException { Map map = mapper.readValue(json, Map.class); System.out.println(map); return json; } }

然后我们启动项目，打开ip:port/swagger-ui.html:

不输入任何参数，点击try it out!按钮：

从页面上我们可以看到我们在接口的头部指定的接口类描述(@Api)，以及在接口方法上指定的方法描述(@ApiOperation)，在接口参数上指定的参数描述(@ApiParam)都已经生效，这都是基于swagger来实现的，但是需要注意的是swagger只能提供接口的描述信息。

3.额外的学习经历

我在使用swagger的时候，遇到一个需求是这样的，我需要在两个接口层都使用swagger，即将两个接口层的api分组展示，例如下面这两个接口层：

我启动项目后访问swagger页面，发现一个很奇怪的问题，就是other层的接口看不到：

我猜测原因可能是我在配置类中指定的接口层位置影响了swagger api的显示。于是我百度了一下，找到一个解决方案，就是不指定接口层的位置，而指定注解的@RestController

@Bean public Docket restApi() { return new Docket(DocumentationType.SWAGGER_2) .groupName("standard") .apiInfo(apiInfo("Spring Boot中使用Swagger2构建RESTful APIs", "1.0")) .useDefaultResponseMessages(true) .forCodeGeneration(false) .select() // .apis(RequestHandlerSelectors.basePackage("com.xqnode.learning.controller")) .apis(RequestHandlerSelectors.withClassAnnotation(RestController.class)) .paths(PathSelectors.any()) .build(); }

swagger界面中出现了另一个接口的api：

但是这样的效果并不好。大家试想一下，我们为什么要对接口分层呢？不就是为了将业务隔离么，这样在一个界面中出现两个接口层的api，对于我们查找接口非常的不方便，也打乱了我们对接口分层的目的。那么怎么才能将其进行隔离开呢？

其实很简单，我们只需要重新定义一个Docket的bean，在其中指定另外接口层的位置即可：

@Bean public Docket restApi2() { return new Docket(DocumentationType.SWAGGER_2) .groupName("其他接口") .apiInfo(apiInfo("Other APIs", "2.0")) .select() .apis(RequestHandlerSelectors.basePackage("com.xqnode.learning.other")) .paths(PathSelectors.regex("/other.*")) .build(); }

我们在这里指定了第二个接口层的位置，同时指定了它的路径前缀，这样我们在swagger页面中就能很方便很清晰的找到它里面的接口了。

接口层1：标准接口

接口层2：其他接口

现在我们只要通过切换分组，就可以找到我们关注的接口层的api了。

下面贴出完整的配置类：

@Configuration @EnableSwagger2 public class SwaggerConfig { /** * 创建API应用 * apiInfo() 增加API相关信息 * 通过select()函数返回一个ApiSelectorBuilder实例,用来控制哪些接口暴露给Swagger来展现， * 本例采用指定扫描的包路径来定义指定要建立API的目录。 * * @return */ @Bean public Docket restApi() { return new Docket(DocumentationType.SWAGGER_2) .groupName("standard") .apiInfo(apiInfo("Spring Boot中使用Swagger2构建RESTful APIs", "1.0")) .useDefaultResponseMessages(true) .forCodeGeneration(false) .select() .apis(RequestHandlerSelectors.basePackage("com.xqnode.learning.controller")) // .apis(RequestHandlerSelectors.withClassAnnotation(RestController.class)) .paths(PathSelectors.regex("/api.*")) .build(); } @Bean public Docket restApi2() { return new Docket(DocumentationType.SWAGGER_2) .groupName("其他接口") .apiInfo(apiInfo("Other APIs", "2.0")) .select() .apis(RequestHandlerSelectors.basePackage("com.xqnode.learning.other")) .paths(PathSelectors.regex("/other.*")) .build(); } /** * 创建该API的基本信息（这些基本信息会展现在文档页面中） * 访问地址：ip:port/swagger-ui.html * * @return */ private ApiInfo apiInfo(String title, String version) { return new ApiInfoBuilder() .title(title) .description("更多请关注: jb51.net") .termsOfServiceUrl("jb51.net") .contact(new Contact("xqnode", "jb51.net", "xiaqingweb@163.com")) .version(version) .build(); } }

至此，springboot集成swagger2完成，同时加了一个餐，还满意吧？哈哈

以上这篇SpringBoot集成swagger-ui以及swagger分组显示操作就是小编分享给大家的全部内容了，希望能给大家一个参考，也希望大家多多支持易盾网络。