1、添加依赖
2、设置配置类
4、Controller 类配置
@Api的使用
API作用在Controller,作为swagger文档资源,该注解将一个controller标注为一个Swagger资源(API). 在默认情况下,Swagger-Core 只会扫描解析具有 @Api 注解的类,而会自动忽略其他类别资源(JAX-RS endpoints、Servlets 等)的注解。
@ApiOperation 的使用
ApiOperation 定义在方法上,描述方法名、方法解释、返回信息、标记等信息。
@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.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 |
用在出入参数对象的字段上 |
【推荐】编程新体验,更懂你的AI,立即体验豆包MarsCode编程助手
【推荐】凌霞软件回馈社区,博客园 & 1Panel & Halo 联合会员上线
【推荐】抖音旗下AI助手豆包,你的智能百科全书,全免费不限次数
【推荐】轻量又高性能的 SSH 工具 IShell:AI 加持,快人一步