一、前言
开发项目时,免不了需要进行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.SPRING_WEB) //文档head主体 .apiInfo(this.apiInfo()) //生成Controller的api文档 .select() .apis(RequestHandlerSelectors.basePackage("com.zzb.test.admin.controller")) .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、测试结果