Spring Boot笔记(一) springboot 集成 swagger-ui

个人博客网：https://wushaopei.github.io/    (你想要这里多有)

1、添加依赖

                <!--SpringBoot整合Swagger-ui-->
                <dependency>
			<groupId>io.springfox</groupId>
			<artifactId>springfox-swagger2</artifactId>
			<version>2.9.2</version>
		</dependency>

		<!-- https://mvnrepository.com/artifact/io.springfox/springfox-swagger-ui -->
		<dependency>
			<groupId>io.springfox</groupId>
			<artifactId>springfox-swagger-ui</artifactId>
			<version>2.9.2</version>
		</dependency>

2、设置配置类

​

package com.example.poiutis.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.service.Contact; import springfox.documentation.spi.DocumentationType; import springfox.documentation.spring.web.plugins.Docket; import springfox.documentation.swagger2.annotations.EnableSwagger2; /** * @ClassName SwaggerConfig * @Description TODO * @Author wushaopei * @Date 2019/7/22 16:05 * @Version 1.0 */ // 启动时加载类 @Configuration // 启用Swagger API文档 @EnableSwagger2 public class SwaggerConfig { @Bean public Docket api() { return new Docket(DocumentationType.SWAGGER_2) .apiInfo(apiInfo()) .select() // 自行修改为自己的包路径 .apis(RequestHandlerSelectors.basePackage("com.example.poiutis.controller")) .paths(PathSelectors.any()) .build(); } private ApiInfo apiInfo() { return new ApiInfoBuilder() .title("报表管理") .description("报表管理中心 API 1.0 操作文档") //服务条款网址 .termsOfServiceUrl("https://blog.csdn.net/weixin_42405670") .version("1.0") .contact(new Contact("鮀城小帅", "https://blog.csdn.net/weixin_42405670", "[e-mail]")) .build(); } }

3、启动类加上注解@EnableSwagger
启动该注解使得用在controller中的swagger注解生效，覆盖的范围下的所有controller

​

4、Controller 类配置

@Api的使用

API作用在Controller,作为swagger文档资源,该注解将一个controller标注为一个Swagger资源(API). 在默认情况下，Swagger-Core 只会扫描解析具有 @Api 注解的类，而会自动忽略其他类别资源（JAX-RS endpoints、Servlets 等）的注解。

@ApiOperation 的使用

ApiOperation 定义在方法上，描述方法名、方法解释、返回信息、标记等信息。

/** * 发票管理 * @author issuser * */ @Api(value = "发票",description = "发票操作 API", position = 100, protocols = "http") @RestController @RequestMapping(value = "/webcode") public class InvoiceController { private static Logger logger = LoggerFactory.getLogger(InvoiceController.class); @Autowired invoiceOrderService InvoiceOrderService; @ApiOperation(value = "导出操作日志到xls文件", notes = "需要登录") @GetMapping("/exporInvoiceOrderXls") @ResponseBody public Object exporInvoiceOrderXls( HttpServletRequest request, HttpServletResponse response, @RequestParam(value="invoiceOrders")@ApiParam(value="invoiceOrders") List<String> invoiceOrders) { Map<String, Object> map = new HashMap<>(); response.setContentType("octets/stream"); Map<String, Object> map2 = new HashMap<String, Object>(); map2.put("sheetTitle", "消费记录"); map2.put("header", new String[]{"订单号", "商店名称", "发票批次", "账户名称", "商店地址", "刷卡账号","商店电话","信用卡开户行名称"}); map2.put("fields", new String[]{"invoiceOrder", "companyName", "taxNumber", "accountBank", "companyAddress","bankNumber","companyTelephone","accountName"}); List<InvoiceOrder> invoiceOrderss = InvoiceOrderService.queryInvoiceLists(invoiceOrders,0,9999); map2.put("data",invoiceOrderss); List<Map<String, Object>> list = new ArrayList<>(); list.add(map2); String title = "日常消费刷卡发票记录"; Map<String, short[]> mergedRegion = new HashMap<String, short[]>(); mergedRegion.put("通用标题名称合并", new short[] {0, 0, 0, 100}); ExportExcel<InvoiceOrder> ex = new ExportExcel<>(); // 声明一个工作薄 HSSFWorkbook workbook = new HSSFWorkbook(); // 生成一个标题样式 HSSFCellStyle headerStyle = ex.cellStyle(workbook); // 生成一个内容样式 HSSFCellStyle textStyle = ex.cellStyle(workbook); // 生成标题字体 ex.setFont(workbook, headerStyle, (short) 10, HSSFFont.BOLDWEIGHT_NORMAL); // 生成内容字体 ex.setFont(workbook, textStyle, HSSFFont.BOLDWEIGHT_NORMAL); try { OutputStream out = response.getOutputStream(); // 导出文件名称添加当前时间 String date = new SimpleDateFormat("yyyyMMddHHmmss").format(new Date()); //防止乱码 // response.addHeader("Access-Control-Expose-Headers", "Content-Type,Content-Disposition"); // response.addHeader("Content-Disposition", // "attachment;filename=" + URLEncoder.encode(title, "GBK") + date // + ".xls"); response.setHeader("Content-Disposition", "attachment; filename=" + new String((title+".xls").getBytes("GB2312"),"ISO8859-1")); list.forEach(m -> { ExcelModel excelModel = new ExcelModel(); excelModel.setWorkbook(workbook); excelModel.setTitle(title); excelModel.setFields((String[]) m.get("fields")); excelModel.setHeader((String[]) m.get("header")); excelModel.setHeaderRow(2); excelModel.setMergedRegion(mergedRegion); excelModel.setHeaderStyle(headerStyle); excelModel.setTextStyle(textStyle); excelModel.setTitles((String) m.get("sheetTitle")); // 生成一页表格 HSSFSheet sheet = workbook.createSheet((String) m.get("sheetTitle")); excelModel.setSheet(sheet); ex.exportExcel(excelModel, (Collection<InvoiceOrder>) m.get("data")); }); try { workbook.write(out); } catch (IOException e) { e.printStackTrace(); }finally { out.close(); } map.put("state","0"); map.put("message", "导出成功"); return map; } catch (IOException e) { e.printStackTrace(); map.put("state", "1"); map.put("message", e.getMessage()); return map; } } }

属性名称	备注
value	url 的路径值
tags	如果设置这个值，value 的值会被覆盖
description	对 API 资源的描述
produces	For example, "application/json, application/xml"
consumes	For example, "application/json, application/xml"
protocols	Possible values: http, https, ws, wss
authorizations	高级特性认证时配置
hidden	配置为 true 将在文档中隐藏
response	返回的对象
responseContainer	这些对象是有效的 "List", "Set" or "Map"，其他无效
httpMethod	"GET"、"HEAD"、"POST"、"PUT"、"DELETE"、"OPTIONS" and "PATCH"
code	http 的状态码 默认 200
extensions	扩展属性

@ApiImplicitParams 和 @ApiImplicitParam 的使用

@ApiImplicitParams 用于描述方法的返回信息，和 @ApiImplicitParam 注解配合使用；@ApiImplicitParam 用来描述具体某一个参数的信息，包括参数的名称、类型、限制等信息。

5、启动项目，进入API列表，localhost/swagger-ui.html#

​

完整springBoot 整合 Swagger 代码 GitHub 链接地址：

注意问题：

出现以下问题时，要检查SwaggerConfig 中配置的路径是否正确；

​

即：

​

GitHub

6、Swagger常用注解

作用范围	API	使用位置
协议集描述	@Api	用于 Controller 类上
协议描述	@ApiOperation	用在 Controller 的方法上
非对象参数集	@ApiImplicitParams	用在 Controller 的方法上
非对象参数描述	@ApiImplicitParam	用在 @ApiImplicitParams 的方法里边
响应集	@ApiResponses	用在 Controller 的方法上
响应信息参数	@ApiResponse	用在 @ApiResponses 里边
描述返回对象的意义	@ApiModel	用在返回对象类上
对象属性	@ApiModelProperty	用在出入参数对象的字段上