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", "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 中配置的路径是否正确；

​

即：

​

GitHub

6、Swagger常用注解

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