电商项目实战（架构二）——Swagger-UI实现在线api文档

一、前言

　　开发项目时，免不了需要进行api接口的测试，为了方便快速高效的进行此过程，本次进行Swagger-UI在线文档的注解实现。

二、框架介绍

　　HTML，Javascript，CSS，根据三种语言动态的根据注解生成在线文档。

三、常用注解

　　@Api：用于修饰Controller类，生成Controller相关文档信息。

　　@ApiOpration：用于修饰Controller类内的方法，生成其方法的相关文档信息。

　　@ApiParams：用于修饰接口方法中的参数，生成其参数的相关文档信息。

　　@ApiModelProperty：用于修饰实体类的属性，生成请求参数或返回结果的相关文档信息。

四、内容

　　1、添加pom依赖

<!--Swagger-UI API文档生产工具-->
        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-swagger2</artifactId>
            <version>2.7.0</version>
        </dependency>
        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-swagger-ui</artifactId>
            <version>2.7.0</version>
        </dependency>

　　2、在config包下新建Swagger-UI的配置类SwaggerConfig

package com.zzb.test.admin.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.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2;

/**
 * Swagger-UI的配置类
 * Created by zzb on 2019/11/18 18:14
 */
@Configuration
@EnableSwagger2
public class SwaggerConfig {

    @Bean
    public Docket createApi(){
        return new Docket(DocumentationType.SWAGGER_2)
                //文档head主体
                .apiInfo(this.apiInfo())
                //生成Controller的api文档
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.zzb.test.admin.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("Swagger-UI演示")
                .description("shop-test")
                .version("1.0.0")
                .build();
    }
}

　　3、在Controller类添加注解

package com.zzb.test.admin.controller;

import com.zzb.test.admin.common.CommonPage;
import com.zzb.test.admin.common.CommonResult;
import com.zzb.test.admin.mbg.model.PmsBrand;
import com.zzb.test.admin.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.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RequestMethod;
import org.springframework.web.bind.annotation.RequestParam;
import org.springframework.web.bind.annotation.ResponseBody;

import java.util.List;

/**
 * 品牌管理Controller
 * Created by zzb on 2019/11/15 10:28
 */
@Api(tags = "PmsBrandController: 商品品牌管理")
@Controller
public class PmsBrandController {

    @Autowired
    private PmsBrandService pmsBrandService;

    private static final Logger logger = LoggerFactory.getLogger(PmsBrandController.class);

    @ApiOperation("分页获取所有品牌")
    @RequestMapping(value = "/admin/brand/getList", method = RequestMethod.GET)
    @ResponseBody
    public CommonResult<CommonPage<PmsBrand>> getList(@RequestParam(value = "pageNum", defaultValue = "1") @ApiParam("分页页码") Integer pageNum,
                                                           @RequestParam(value = "pageSize", defaultValue = "10") @ApiParam("每页数量") Integer pageSize){
        List<PmsBrand> list = pmsBrandService.getList(pageNum,pageSize);
        logger.info("分页查询所有品牌==》" + list);
        return CommonResult.success(CommonPage.restPage(list));
    }

    @ApiOperation("添加品牌")
    @RequestMapping(value = "/admin/brand/insert", method = RequestMethod.POST)
    @ResponseBody
    public CommonResult insert(@ApiParam("品牌信息") PmsBrand pmsBrand){
        int count = pmsBrandService.insert(pmsBrand);
        logger.info("添加品牌==》" + count);
        if (count>0) {
            return CommonResult.success("添加品牌成功");
        }
        return CommonResult.failed();
    }

    @ApiOperation("删除品牌")
    @RequestMapping(value = "/admin/brand/delete", method = RequestMethod.POST)
    @ResponseBody
    public CommonResult delete(@ApiParam("品牌id") Long id){
        int count = pmsBrandService.delete(id);
        logger.info("删除品牌==》" + count);
        if (count>0) {
            return CommonResult.success("删除品牌成功");
        }
        return CommonResult.failed();
    }

    @ApiOperation("更新品牌")
    @RequestMapping(value = "/admin/brand/update", method = RequestMethod.POST)
    @ResponseBody
    public CommonResult update(@ApiParam("修改主体") PmsBrand pmsBrand){
        int count = pmsBrandService.update(pmsBrand);
        logger.info("更新品牌==》" + count);
        if (count>0) {
            return CommonResult.success("更新品牌成功");
        }
        return CommonResult.failed();
    }

}

　　4、测试结果

　　

　　项目github地址：https://github.com/18372561381/shoptest