Swagger-UI实现在线API文档

Swagger-UI 自动生成接口文档，不需要频繁更新接口文档，保证接口文档与代码的一致。

依赖添加

<!--Swagger-UI API文档生产工具-->
<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-boot-starter</artifactId>
    <version>3.0.0</version>
</dependency>

新增Swagger配置类

/**
 * Swagger2API文档的配置
 * Create By songzb on 2020/10/19
 */
@Configuration
@EnableSwagger2
public class Swagger2Config {

    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("SwaggerUI演示")
                .description("demo-mall")
                .contact(new Contact("songzblink", "https://zbsong.top", "songzblink@163.com"))
                .version("1.1")
                .build();
    }

    @Bean
    public Docket createRestApi() {
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .select()
                // 为当前包下controller生成API文档
                .apis(RequestHandlerSelectors.basePackage("com.songzb.demomall.controller"))
                // 为所有@Api注解的Controller生成API文档
                // .apis(RequestHandlerSelectors.withClassAnnotation(Api.class)
                // 为有@ApiOperation注解的方法生成API文档
                // .apis(RequestHandlerSelectors.withMethodAnnotation(ApiOperation.class))
                .paths(PathSelectors.any())
                .build();
    }
}

在Controller类上添加Swagger注解

/**
 * 品牌管理Controller
 * Create By songzb on 2020/10/16
 */
@Api(tags = "PmsBrandController", value = "商品品牌管理")
@Controller
@RequestMapping("/brand")
@Slf4j
public class PmsBrandController {

    @Autowired
    private PmsBrandService pmsBrandService;

    @ApiOperation("获取所有品牌列表")
    @RequestMapping(value = "/listAll", method = RequestMethod.GET)
    @ResponseBody
    public CommonResult<List<PmsBrand>> getBrandList() {
        log.debug("getBrandList()");
        return CommonResult.success(pmsBrandService.listAllBrand());
    }

    @ApiOperation("添加品牌")
    @RequestMapping(value = "/create", method = RequestMethod.POST)
    @ResponseBody
    public CommonResult createBrand(@RequestBody PmsBrand pmsBrand) {
        CommonResult commonResult = null;
        int res = pmsBrandService.creatBrand(pmsBrand);
        if (res == 1) {
            commonResult = CommonResult.success(pmsBrand);
            log.debug("creatBrand success:{}", pmsBrand);
        } else {
            commonResult = CommonResult.failed("操作失败");
            log.debug("creatBrand failed:{}", pmsBrand);
        }
        return commonResult;
    }

    @ApiOperation("更新指定id品牌信息")
    @RequestMapping(value = "/update/{id}", method = RequestMethod.POST)
    @ResponseBody
    public CommonResult updateBrand(@PathVariable("id") Long id, @RequestBody PmsBrand pmsBrand, BindingResult result) {
        CommonResult commonResult = null;
        int res = pmsBrandService.updateBrand(id, pmsBrand);
        if (res == 1) {
            commonResult = CommonResult.success(pmsBrand);
            log.debug("updateBrand success: id={}", id);
        } else {
            commonResult = CommonResult.failed("操作失败");
            log.debug("creatBrand failed: id={}", id);
        }
        return commonResult;
    }

    @ApiOperation("删除指定id的品牌")
    @RequestMapping(value = "/delete/{id}", method = RequestMethod.GET)
    @ResponseBody
    public CommonResult deleteBrand(@PathVariable("id") Long id) {
        CommonResult commonResult = null;
        int res = pmsBrandService.deleteBrand(id);
        if (res == 1) {
            log.debug("deleteBrand success: id={}", id);
            commonResult = CommonResult.success(null);
        } else {
            log.debug("deleteBrand failed:{}", id);
            commonResult = CommonResult.failed("操作失败");
        }
        return commonResult;
    }

    @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 = pmsBrandService.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(pmsBrandService.getBrand(id));
    }
}

在实体类上添加Swagger注解

/**
 * Create By songzb on 2020/10/16
 */
@Data
@Table(name = "pms_brand")
public class PmsBrand {
    // 设置主键
    @Id
    // 主键回填，当写入没有指定 id 时，数据库自增生成一个 id，然后回填到这里
    @KeySql(useGeneratedKeys = true)
    private Long id;
    private String name;
    @ApiModelProperty(value = "首字母")
    private String firstLetter;
    private Integer sort;
    @ApiModelProperty(value = "是否为品牌制造商：0->不是；1->是")
    private Integer factoryStatus;
    private Integer showStatus;
    @ApiModelProperty(value = "产品数量")
    private Integer productCount;
    @ApiModelProperty(value = "产品评论数量")
    private Integer productCommentCount;
    @ApiModelProperty(value = "品牌logo")
    private String logo;
    @ApiModelProperty(value = "专区大图")
    private String bigPic;
    @ApiModelProperty(value = "品牌故事")
    private String brandStory;
}