SpringBoot入门建站全系列（十六）整合Swagger文档中心

雨点打透心脏的1/2处 2021-12-11 02:21 342阅读 0赞

## SpringBoot入门建站全系列（十六）整合Swagger文档中心 ##

#### 一、概述 ####

Swagger 是一个规范和完整的框架，用于生成、描述、调用和可视化 RESTful 风格的 Web 服务。总体目标是使客户端和文件系统作为服务器以同样的速度来更新 。接口的方法，参数和模型紧密集成到服务器端的代码，允许API来始终保持同步。Swagger 让部署管理和使用功能强大的API从未如此简单。

swagger可以与Spring MVC程序配合组织出强大RESTful API文档。它既可以减少我们创建文档的工作量，同时说明内容又整合入实现代码中，让维护文档和修改代码整合为一体，可以让我们在修改代码逻辑的同时方便的修改文档说明。另外Swagger2也提供了强大的页面测试功能 来调试每个RESTful API。

代码可以在Spring组件化构建[https://www.pomit.cn/java/spring/springboot.html][https_www.pomit.cn_java_spring_springboot.html]中的Swagger组件中查看，并下载。

首发地址：  
[品茗IT-同步发布][IT-]

[品茗IT][IT] 提供在线支持：

[一键快速构建Spring项目工具][Spring]

[一键快速构建SpringBoot项目工具][https_www.pomit.cn_java_spring_springboot.html]

[一键快速构建SpringCloud项目工具][SpringCloud]

[一站式Springboot项目生成][Springboot]

[Mysql一键生成Mybatis注解Mapper][Mysql_Mybatis_Mapper]

**如果大家正在寻找一个java的学习环境，或者在开发中遇到困难，可以[加入我们的java学习圈，点击即可加入][java]，共同学习，节约学习时间，减少很多在学习中遇到的难题。**

### 二、配置 ###

本文假设你已经引入spring-boot-starter-web。已经是个SpringBoot项目了,如果不会搭建，可以打开这篇文章看一看[《SpringBoot入门建站全系列（一）项目建立》][SpringBoot]。

#### 2.1 Maven依赖 ####

使用swagger需要引入springfox-swagger2，如果要使用swagger的界面，需要引入springfox-swagger-ui。

<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.2 配置文件 ####

基于注解配置Swagger，暂不需要额外配置参数。

## 三、Swagger配置 ##

### 3.1 开启Swagger ###

SwaggerConfig:

package com.cff.springbootwork.swagger.config;
    
    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
    	public Docket createRestApi() { 
    		return new Docket(DocumentationType.SWAGGER_2)
    				.apiInfo(apiInfo())
    				.select()
    				.apis(RequestHandlerSelectors.basePackage("com.cff.springbootwork"))
    				.paths(PathSelectors.any())
    				.build();
    	}
    
    	private ApiInfo apiInfo() { 
    		return new ApiInfoBuilder()
    				.title("API文档")
    				.description("简单优雅的restful风格")
    				.version("1.0")
    				.build();
    	}
    
    }

这里，@EnableSwagger2开启Swagger。@Configuration注解声明这里可以配置bean。

### 3.2 手动增加Swagger接口说明（可有可无） ###

有时候，Swagger是获取不到一些接口的信息，这样在界面上就无法显示出这些接口信息。如由SpringSecurity控制的登入等登出接口，这时候我们可以手动添加这些接口：

SwaggerAddtionScanConfig：

package com.cff.springbootwork.swagger.config;
    
    import java.util.ArrayList;
    import java.util.Arrays;
    import java.util.Collections;
    import java.util.List;
    import java.util.Set;
    
    import org.springframework.http.HttpMethod;
    import org.springframework.stereotype.Component;
    
    import com.cff.springbootwork.swagger.entity.TestEntity;
    import com.fasterxml.classmate.TypeResolver;
    
    import springfox.documentation.builders.OperationBuilder;
    import springfox.documentation.builders.ParameterBuilder;
    import springfox.documentation.builders.ResponseMessageBuilder;
    import springfox.documentation.schema.ModelRef;
    import springfox.documentation.service.ApiDescription;
    import springfox.documentation.service.ResponseMessage;
    import springfox.documentation.spi.DocumentationType;
    import springfox.documentation.spi.service.ApiListingScannerPlugin;
    import springfox.documentation.spi.service.contexts.DocumentationContext;
    import springfox.documentation.spring.web.readers.operation.CachingOperationNameGenerator;
    
    /** * 该文件可有可无，手动增加接口的方法 * @author fufei * */
    @Component
    public class SwaggerAddtionScanConfig implements ApiListingScannerPlugin { 
    	@Override
    	public List<ApiDescription> apply(DocumentationContext documentationContext) { 
    		return new ArrayList<>(
    				Arrays.asList(
    						new ApiDescription("Login", "/login", "登录接口",
    								Collections
    										.singletonList(
    												new OperationBuilder(new CachingOperationNameGenerator()).authorizations(new ArrayList<>())
    														.method(HttpMethod.POST)
    														.summary("登录接口")                                                
    														.notes("登录接口")//方法描述 
    														.tags(Collections.singleton("登录登出模块"))//归类标签
    														.produces(Collections.singleton("application/json"))
    														.consumes(Collections.singleton("application/json"))
    														.parameters(
    																Arrays.asList(
    																		new ParameterBuilder()
    																				.description("email")
    																				.type(new TypeResolver()
    																						.resolve(String.class))
    																				.name("email")
    																				.parameterType("query")
    																				.parameterAccess("access")
    																				.required(true)
    																				.modelRef(new ModelRef("string"))
    																				.build(),
    																		new ParameterBuilder()
    																		.description("password")
    																		.type(new TypeResolver()
    																				.resolve(String.class))
    																		.name("password")
    																		.parameterType("query")
    																		.parameterAccess("access")
    																		.required(true)
    																		.modelRef(new ModelRef("string"))
    																		.build()
    																				))
    														.responseMessages(responseMessages())
    														.build()),
    								false),
    						new ApiDescription("Login",
    								"/logout", "登出接口",
    								Collections
    										.singletonList(
    												new OperationBuilder(new CachingOperationNameGenerator()).authorizations(new ArrayList<>())
    														.method(HttpMethod.POST)
    														.summary("登出接口")                                                
    														.notes("登出接口")//方法描述 
    														.tags(Collections.singleton("登录登出模块"))//归类标签
    														.produces(Collections.singleton("application/json"))
    														.parameters(
    																Collections
    																		.singletonList(new ParameterBuilder()
    																				.description("token")
    																				.type(new TypeResolver()
    																						.resolve(String.class))
    																				.name("token")
    																				.parameterType("query")
    																				.parameterAccess("access")
    																				.required(true)
    																				.modelRef(new ModelRef("string"))
    																				.build()))
    														.responseMessages(responseMessages())
    														
    														.build()),
    								false)));
    
    	}
    
    	/** * @return Set of response messages that overide the default/global response * messages */
    	private Set<ResponseMessage> responseMessages() {  // <8>
    		return Collections.singleton(
    				new ResponseMessageBuilder().code(200).message("Successfully received bug 1767 or 2219 response")
    						.responseModel(new ModelRef(
    								TestEntity.class.getSimpleName())
    								).build());
    	}
    
    	@Override
    	public boolean supports(DocumentationType documentationType) { 
    		return DocumentationType.SWAGGER_2.equals(documentationType);
    	}
    }

## 四、测试Swagger ##

我们使用一些Swagger的注解来做测试，如果不加注解其实也是可以的，但是不方便观看，加注解的话可以显示写的内容。

SwaggerRest ：

package com.cff.springbootwork.swagger.web;
    
    import java.util.UUID;
    
    import org.springframework.web.bind.annotation.RequestMapping;
    import org.springframework.web.bind.annotation.RequestMethod;
    import org.springframework.web.bind.annotation.RequestParam;
    import org.springframework.web.bind.annotation.RestController;
    
    import com.cff.springbootwork.swagger.entity.TestEntity;
    
    import io.swagger.annotations.Api;
    import io.swagger.annotations.ApiOperation;
    
    @Api(tags = { "测试模块"}, produces = "application/json")
    @RestController
    @RequestMapping("/swagger")
    public class SwaggerRest { 
    	
    	@ApiOperation(value = "测试swagger的功能")
    	@RequestMapping(value = "/test", method = {  RequestMethod.GET })
    	public TestEntity test(@RequestParam String reqType) { 
    		String uuid = UUID.randomUUID().toString();
    		String welMsg = "welcome 程序猿";
    		if (reqType != null && "1000".equals(reqType)) { 
    			welMsg = "welcome 程序媛";
    		}
    		TestEntity welEntity = new TestEntity();
    		welEntity.setUuid(uuid);
    		welEntity.setWelMsg(welMsg);
    		return welEntity;
    	}
    	
    	@RequestMapping(value = "/test2", method = {  RequestMethod.GET })
    	public TestEntity test2(@RequestParam String reqType) { 
    		String uuid = UUID.randomUUID().toString();
    		String welMsg = "welcome 程序猿";
    		if (reqType != null && "1000".equals(reqType)) { 
    			welMsg = "welcome 程序媛";
    		}
    		TestEntity welEntity = new TestEntity();
    		welEntity.setUuid(uuid);
    		welEntity.setWelMsg(welMsg);
    		return welEntity;
    	}
    }

## 五、过程中用到的实体 ##

TestEntity：

package com.cff.springbootwork.swagger.entity;
    
    public class TestEntity { 
    	private String uuid;
    	private String welMsg;
    	public String getUuid() { 
    		return uuid;
    	}
    	public void setUuid(String uuid) { 
    		this.uuid = uuid;
    	}
    	public String getWelMsg() { 
    		return welMsg;
    	}
    	public void setWelMsg(String welMsg) { 
    		this.welMsg = welMsg;
    	}
    }

### 快速构建项目 ###

[Spring组件化构建][Spring]

[SpringBoot组件化构建][https_www.pomit.cn_java_spring_springboot.html]

[SpringCloud服务化构建][SpringCloud]

喜欢这篇文章么，喜欢就加入我们一起讨论SpringBoot使用吧！  
![品茗IT交流群][IT 1]

[https_www.pomit.cn_java_spring_springboot.html]: https://www.pomit.cn/java/spring/springboot.html
[IT-]: https://www.pomit.cn/p/1972641730808321
[IT]: https://www.pomit.cn
[Spring]: https://www.pomit.cn/java/spring/spring.html
[SpringCloud]: https://www.pomit.cn/java/spring/springcloud.html
[Springboot]: https://www.pomit.cn/java/java/sqlToSpringboot.html
[Mysql_Mybatis_Mapper]: https://www.pomit.cn/java/java/sqlToMybatis.html
[java]: https://jq.qq.com/?_wv=1027&k=52sgH1J
[SpringBoot]: https://www.pomit.cn/p/169774771175680
[IT 1]: /images/20211210/24b1ae57b4b945ab94dc8c791504b707.png