社区微信群开通啦,扫一扫抢先加入社区官方微信群
社区微信群
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", "15989746839@163.com"))
.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 中配置的路径是否正确;
即:
6、Swagger常用注解
作用范围 | API | 使用位置 |
---|---|---|
协议集描述 | @Api | 用于 Controller 类上 |
协议描述 | @ApiOperation | 用在 Controller 的方法上 |
非对象参数集 | @ApiImplicitParams | 用在 Controller 的方法上 |
非对象参数描述 | @ApiImplicitParam | 用在 @ApiImplicitParams 的方法里边 |
响应集 | @ApiResponses | 用在 Controller 的方法上 |
响应信息参数 | @ApiResponse | 用在 @ApiResponses 里边 |
描述返回对象的意义 | @ApiModel | 用在返回对象类上 |
对象属性 | @ApiModelProperty | 用在出入参数对象的字段上 |
如果觉得我的文章对您有用,请随意打赏。你的支持将鼓励我继续创作!