锐客网

  1. 首页 > it技术 > >

mall整合Swagger-UI实现在线API文档

本文主要讲解mall是如何通过整合Swagger-UI来实现一份相当完善的在线API文档的。
项目使用框架介绍
Swagger-UI
Swagger-UI是HTML, Javascript, CSS的一个集合，可以动态地根据注解生成在线API文档。
常用注解
@Api：用于修饰Controller类，生成Controller相关文档信息
@ApiOperation：用于修饰Controller类中的方法，生成接口方法相关文档信息
@ApiParam：用于修饰接口中的参数，生成接口参数相关文档信息
@ApiModelProperty：用于修饰实体类的属性，当实体类是请求参数或返回结果时，直接生成相关文档信息
整合Swagger-UI
添加项目依赖
在pom.xml中新增Swagger-UI相关依赖
io.springfoxspringfox-swagger22.7.0io.springfoxspringfox-swagger-ui2.7.0Copy to clipboardErrorCopied
添加Swagger-UI的配置
添加Swagger-UI的Java配置文件
注意：Swagger对生成API文档的范围有三种不同的选择
生成指定包下面的类的API文档
生成有指定注解的类的API文档
生成有指定注解的方法的API文档
packagecom.macro.mall.tiny.config; importorg.springframework.context.annotation.Bean; importorg.springframework.context.annotation.Configuration; importspringfox.documentation.builders.ApiInfoBuilder; importspringfox.documentation.builders.PathSelectors; importspringfox.documentation.builders.RequestHandlerSelectors; importspringfox.documentation.service.ApiInfo; importspringfox.documentation.spi.DocumentationType; importspringfox.documentation.spring.web.plugins.Docket; importspringfox.documentation.swagger2.annotations.EnableSwagger2; /**
* Swagger2API文档的配置
*/@Configuration@EnableSwagger2publicclassSwagger2Config{@BeanpublicDocketcreateRestApi(){returnnewDocket(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(); }privateApiInfoapiInfo(){returnnewApiInfoBuilder().title("SwaggerUI演示").description("mall-tiny").contact("macro").version("1.0").build(); }}Copy to clipboardErrorCopied
给PmsBrandController添加Swagger注解
给原有的品牌管理Controller添加上Swagger注解
packagecom.macro.mall.tiny.controller; importcom.macro.mall.tiny.common.api.CommonPage; importcom.macro.mall.tiny.common.api.CommonResult; importcom.macro.mall.tiny.mbg.model.PmsBrand; importcom.macro.mall.tiny.service.PmsBrandService; importio.swagger.annotations.Api; importio.swagger.annotations.ApiOperation; importio.swagger.annotations.ApiParam; importorg.slf4j.Logger; importorg.slf4j.LoggerFactory; importorg.springframework.beans.factory.annotation.Autowired; importorg.springframework.stereotype.Controller; importorg.springframework.validation.BindingResult; importorg.springframework.web.bind.annotation.*; importjava.util.List; /**
* 品牌管理Controller
* Created by macro on 2019/4/19.
*/@Api(tags="PmsBrandController",description="商品品牌管理")@Controller@RequestMapping("/brand")publicclassPmsBrandController{@AutowiredprivatePmsBrandServicebrandService; privatestaticfinalLoggerLOGGER=LoggerFactory.getLogger(PmsBrandController.class); @ApiOperation("获取所有品牌列表")@RequestMapping(value="https://www.it610.com/article/listAll",method=RequestMethod.GET)@ResponseBodypublicCommonResultgetBrandList(){returnCommonResult.success(brandService.listAllBrand()); }@ApiOperation("添加品牌")@RequestMapping(value="https://www.it610.com/create",method=RequestMethod.POST)@ResponseBodypublicCommonResultcreateBrand(@RequestBodyPmsBrandpmsBrand){CommonResultcommonResult; intcount=brandService.createBrand(pmsBrand); if(count==1){commonResult=CommonResult.success(pmsBrand); LOGGER.debug("createBrand success:{}",pmsBrand); }else{commonResult=CommonResult.failed("操作失败"); LOGGER.debug("createBrand failed:{}",pmsBrand); }returncommonResult; }@ApiOperation("更新指定id品牌信息")@RequestMapping(value="https://www.it610.com/update/{id}",method=RequestMethod.POST)@ResponseBodypublicCommonResultupdateBrand(@PathVariable("id")Longid,@RequestBodyPmsBrandpmsBrandDto,BindingResultresult){CommonResultcommonResult; intcount=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); }returncommonResult; }@ApiOperation("删除指定id的品牌")@RequestMapping(value="https://www.it610.com/delete/{id}",method=RequestMethod.GET)@ResponseBodypublicCommonResultdeleteBrand(@PathVariable("id")Longid){intcount=brandService.deleteBrand(id); if(count==1){LOGGER.debug("deleteBrand success :id={}",id); returnCommonResult.success(null); }else{LOGGER.debug("deleteBrand failed :id={}",id); returnCommonResult.failed("操作失败"); }}@ApiOperation("分页查询品牌列表")@RequestMapping(value="https://www.it610.com/list",method=RequestMethod.GET)@ResponseBodypublicCommonResultlistBrand(@RequestParam(value="https://www.it610.com/article/pageNum",defaultValue="https://www.it610.com/article/1")@ApiParam("页码")IntegerpageNum,@RequestParam(value="https://www.it610.com/article/pageSize",defaultValue="https://www.it610.com/article/3")@ApiParam("每页数量")IntegerpageSize){ListbrandList=brandService.listBrand(pageNum,pageSize); returnCommonResult.success(CommonPage.restPage(brandList)); }@ApiOperation("获取指定id的品牌详情")@RequestMapping(value="https://www.it610.com/{id}",method=RequestMethod.GET)@ResponseBodypublicCommonResultbrand(@PathVariable("id")Longid){returnCommonResult.success(brandService.getBrand(id)); }}Copy to clipboardErrorCopied
修改MyBatis Generator注释的生成规则
CommentGenerator为MyBatis Generator的自定义注释生成器，修改addFieldComment方法使其生成Swagger的@ApiModelProperty注解来取代原来的方法注释，添加addJavaFileComment方法，使其能在import中导入@ApiModelProperty，否则需要手动导入该类，在需要生成大量实体类时，是一件非常麻烦的事。
packagecom.macro.mall.tiny.mbg; importorg.mybatis.generator.api.IntrospectedColumn; importorg.mybatis.generator.api.IntrospectedTable; importorg.mybatis.generator.api.dom.java.CompilationUnit; importorg.mybatis.generator.api.dom.java.Field; importorg.mybatis.generator.api.dom.java.FullyQualifiedJavaType; importorg.mybatis.generator.internal.DefaultCommentGenerator; importorg.mybatis.generator.internal.util.StringUtility; importjava.util.Properties; /**
* 自定义注释生成器
* Created by macro on 2018/4/26.
*/publicclassCommentGeneratorextendsDefaultCommentGenerator{privatebooleanaddRemarkComments=false; privatestaticfinalStringEXAMPLE_SUFFIX="Example"; privatestaticfinalStringAPI_MODEL_PROPERTY_FULL_CLASS_NAME="io.swagger.annotations.ApiModelProperty"; /**
* 设置用户配置的参数
*/@OverridepublicvoidaddConfigurationProperties(Propertiesproperties){super.addConfigurationProperties(properties); this.addRemarkComments=StringUtility.isTrue(properties.getProperty("addRemarkComments")); }/**
* 给字段添加注释
*/@OverridepublicvoidaddFieldComment(Fieldfield,IntrospectedTableintrospectedTable,IntrospectedColumnintrospectedColumn){Stringremarks=introspectedColumn.getRemarks(); //根据参数和备注信息判断是否添加备注信息if(addRemarkComments&&StringUtility.stringHasValue(remarks)){//addFieldJavaDoc(field, remarks); //数据库中特殊字符需要转义if(remarks.contains("\"")){remarks=remarks.replace("\"","'"); }//给model的字段添加swagger注解field.addJavaDocLine("@ApiModelProperty(value = https://www.it610.com/""+remarks+"\")"); }}/**
* 给model的字段添加注释
*/privatevoidaddFieldJavaDoc(Fieldfield,Stringremarks){//文档注释开始field.addJavaDocLine("/**"); //获取数据库字段的备注信息String[]remarkLines=remarks.split(System.getProperty("line.separator")); for(StringremarkLine:remarkLines){field.addJavaDocLine(" * "+remarkLine); }addJavadocTag(field,false); field.addJavaDocLine(" */"); }@OverridepublicvoidaddJavaFileComment(CompilationUnitcompilationUnit){super.addJavaFileComment(compilationUnit); //只在model中添加swagger注解类的导入if(!compilationUnit.isJavaInterface()&&!compilationUnit.getType().getFullyQualifiedName().contains(EXAMPLE_SUFFIX)){compilationUnit.addImportedType(newFullyQualifiedJavaType(API_MODEL_PROPERTY_FULL_CLASS_NAME)); }}}Copy to clipboardErrorCopied
运行代码生成器重新生成mbg包中的代码
运行com.macro.mall.tiny.mbg.Generator的main方法，重新生成mbg中的代码，可以看到PmsBrand类中已经自动根据数据库注释添加了@ApiModelProperty注解
mall整合Swagger-UI实现在线API文档
文章图片
运行项目，查看结果
访问Swagger-UI接口文档地址
接口地址：http://localhost:8080/swagger-ui.html
mall整合Swagger-UI实现在线API文档
文章图片
对请求参数已经添加说明
mall整合Swagger-UI实现在线API文档
文章图片
对返回结果已经添加说明
【mall整合Swagger-UI实现在线API文档】直接在在线文档上面进行接口测试
mall整合Swagger-UI实现在线API文档
文章图片

    推荐阅读


    上一篇：集训第17天

    下一篇：寻找自己的旅程