SpringBoot 整合 Swagger2

一、简介：

Swagger 是一个规范和完整的框架，用于生成、描述、调用和可视化 RESTful 风格的 Web 服务。总体目标是使客户端和文件系统作为服务器以同样的速度来更新。文件的方法，参数和模型紧密集成到服务器端的代码，允许API来始终保持同步。

二、作用：

• 接口的文档在线自动生成
• 功能测试

三、使用：

1. 导入Maven坐标

   <!-- swagger2 和 swagger-ui -->
   <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. 添加 Swagger-UI 的 Java 配置文件

   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.spi.DocumentationType;
   import springfox.documentation.spring.web.plugins.Docket;
   import springfox.documentation.swagger2.annotations.EnableSwagger2;
   
   /**
    * Swagger2API文档的配置
    */
   @Configuration
   @EnableSwagger2
   public class Swagger2Config {
       @Bean
       public Docket createRestApi(){
           return new Docket(DocumentationType.SWAGGER_2)
                   .apiInfo(apiInfo())
                   .select()
                   //为当前包下controller生成API文档
                   .apis(RequestHandlerSelectors.basePackage("com.macro.mall.tiny.controller"))
                   //为有@Api注解的Controller生成API文档
                   //.apis(RequestHandlerSelectors.withClassAnnotation(Api.class))
                   //为有@ApiOperation注解的方法生成API文档
                   //.apis(RequestHandlerSelectors.withMethodAnnotation(ApiOperation.class))
                   .paths(PathSelectors.any())
                   .build();
       }
   
       private ApiInfo apiInfo() {
           return new ApiInfoBuilder()
                   .title("SwaggerUI演示")
                   .description("mall-blue")
                   .contact("blue")
                   .version("1.0")
                   .build();
       }
   }
   

3. Controller添加上Swagger注解

   import com.macro.mall.tiny.common.api.CommonPage;
   import com.macro.mall.tiny.common.api.CommonResult;
   import com.macro.mall.tiny.mbg.model.PmsBrand;
   import com.macro.mall.tiny.service.PmsBrandService;
   import io.swagger.annotations.Api;
   import io.swagger.annotations.ApiOperation;
   import io.swagger.annotations.ApiParam;
   import org.slf4j.Logger;
   import org.slf4j.LoggerFactory;
   import org.springframework.beans.factory.annotation.Autowired;
   import org.springframework.stereotype.Controller;
   import org.springframework.validation.BindingResult;
   import org.springframework.web.bind.annotation.*;
   
   import java.util.List;
   
   
   @Api(tags = "PmsBrandController", description = "商品品牌管理")
   @Controller
   @RequestMapping("/brand")
   public class PmsBrandController {
       @Autowired
       private PmsBrandService brandService;
   
       private static final Logger LOGGER = LoggerFactory.getLogger(PmsBrandController.class);
   
       @ApiOperation("获取所有品牌列表")
       @RequestMapping(value = "listAll", method = RequestMethod.GET)
       @ResponseBody
       public CommonResult<List<PmsBrand>> getBrandList() {
           return CommonResult.success(brandService.listAllBrand());
       }
   
       @ApiOperation("添加品牌")
       @RequestMapping(value = "/create", method = RequestMethod.POST)
       @ResponseBody
       public CommonResult createBrand(@RequestBody PmsBrand pmsBrand) {
           CommonResult commonResult;
           int count = brandService.createBrand(pmsBrand);
           if (count == 1) {
               commonResult = CommonResult.success(pmsBrand);
               LOGGER.debug("createBrand success:{}", pmsBrand);
           } else {
               commonResult = CommonResult.failed("操作失败");
               LOGGER.debug("createBrand failed:{}", pmsBrand);
           }
           return commonResult;
       }
   
       @ApiOperation("更新指定id品牌信息")
       @RequestMapping(value = "/update/{id}", method = RequestMethod.POST)
       @ResponseBody
       public CommonResult updateBrand(@PathVariable("id") Long id, @RequestBody PmsBrand pmsBrandDto, BindingResult result) {
           CommonResult commonResult;
           int count = brandService.updateBrand(id, pmsBrandDto);
           if (count == 1) {
               commonResult = CommonResult.success(pmsBrandDto);
               LOGGER.debug("updateBrand success:{}", pmsBrandDto);
           } else {
               commonResult = CommonResult.failed("操作失败");
               LOGGER.debug("updateBrand failed:{}", pmsBrandDto);
           }
           return commonResult;
       }
   
       @ApiOperation("删除指定id的品牌")
       @RequestMapping(value = "/delete/{id}", method = RequestMethod.GET)
       @ResponseBody
       public CommonResult deleteBrand(@PathVariable("id") Long id) {
           int count = brandService.deleteBrand(id);
           if (count == 1) {
               LOGGER.debug("deleteBrand success :id={}", id);
               return CommonResult.success(null);
           } else {
               LOGGER.debug("deleteBrand failed :id={}", id);
               return CommonResult.failed("操作失败");
           }
       }
   
       @ApiOperation("分页查询品牌列表")
       @RequestMapping(value = "/list", method = RequestMethod.GET)
       @ResponseBody
       public CommonResult<CommonPage<PmsBrand>> listBrand(@RequestParam(value = "pageNum", defaultValue = "1")
                                                           @ApiParam("页码") Integer pageNum,
                                                           @RequestParam(value = "pageSize", defaultValue = "3")
                                                           @ApiParam("每页数量") Integer pageSize) {
           List<PmsBrand> brandList = brandService.listBrand(pageNum, pageSize);
           return CommonResult.success(CommonPage.restPage(brandList));
       }
   
       @ApiOperation("获取指定id的品牌详情")
       @RequestMapping(value = "/{id}", method = RequestMethod.GET)
       @ResponseBody
       public CommonResult<PmsBrand> brand(@PathVariable("id") Long id) {
           return CommonResult.success(brandService.getBrand(id));
       }
   }