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

清疚 2021-11-29 19:16 299阅读 0赞

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

1、添加依赖

<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、设置配置类

![20190722171755102.png][]

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

![20190722172009167.png][]

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;
            }
        }
    
    }

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

@ApiImplicitParams 和 @ApiImplicitParam 的使用

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

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

![20190722172320663.png][]

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

注意问题：

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

![20190726103421591.png][]

即：

![20190726103550235.png][]

[GitHub][]

6、Swagger常用注解

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

[https_wushaopei.github.io]: https://wushaopei.github.io/
[20190722171755102.png]: /images/20211129/93123ef4168d4f52b675c3c0914ac60b.png
[20190722172009167.png]: /images/20211129/fb65b92048ce45e185ca87f06d0d828b.png
[20190722172320663.png]: /images/20211129/46e320a156fd41c38c52af771c59b62f.png
[20190726103421591.png]: /images/20211129/9c06950627af458cb3a530a788662215.png
[20190726103550235.png]: /images/20211129/ad6bd0c76e7142168b6fef680fc12da9.png
[GitHub]: https://github.com/wushaopei/SPRING_BOOT/tree/master/spring-boot-swaggerui