本文主要讲解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相关依赖

  1. <!--Swagger-UI API文档生产工具-->
  2. <dependency>
  3.   <groupId>io.springfox</groupId>
  4.   <artifactId>springfox-swagger2</artifactId>
  5.   <version>2.7.0</version>
  6. </dependency>
  7. <dependency>
  8.   <groupId>io.springfox</groupId>
  9.   <artifactId>springfox-swagger-ui</artifactId>
  10.   <version>2.7.0</version>
  11. </dependency>

添加Swagger-UI的配置

添加Swagger-UI的Java配置文件

注意：Swagger对生成API文档的范围有三种不同的选择

  • 生成指定包下面的类的API文档
  • 生成有指定注解的类的API文档
  • 生成有指定注解的方法的API文档
  1. package com.macro.mall.tiny.config;
  3. import org.springframework.context.annotation.Bean;
  4. import org.springframework.context.annotation.Configuration;
  5. import springfox.documentation.builders.ApiInfoBuilder;
  6. import springfox.documentation.builders.PathSelectors;
  7. import springfox.documentation.builders.RequestHandlerSelectors;
  8. import springfox.documentation.service.ApiInfo;
  9. import springfox.documentation.spi.DocumentationType;
  10. import springfox.documentation.spring.web.plugins.Docket;
  11. import springfox.documentation.swagger2.annotations.EnableSwagger2;
  13. /**
  14.  * Swagger2API文档的配置
  15.  */
  16. @Configuration
  17. @EnableSwagger2
  18. public class Swagger2Config {
  19.     @Bean
  20.     public Docket createRestApi(){
  21.         return new Docket(DocumentationType.SWAGGER_2)
  22.                 .apiInfo(apiInfo())
  23.                 .select()
  24.                 //为当前包下controller生成API文档
  25.                 .apis(RequestHandlerSelectors.basePackage("com.macro.mall.tiny.controller"))
  26.                 //为有@Api注解的Controller生成API文档
  27. //                .apis(RequestHandlerSelectors.withClassAnnotation(Api.class))
  28.                 //为有@ApiOperation注解的方法生成API文档
  29. //                .apis(RequestHandlerSelectors.withMethodAnnotation(ApiOperation.class))
  30.                 .paths(PathSelectors.any())
  31.                 .build();
  32.     }
  34.     private ApiInfo apiInfo() {
  35.         return new ApiInfoBuilder()
  36.                 .title("SwaggerUI演示")
  37.                 .description("mall-tiny")
  38.                 .contact("macro")
  39.                 .version("1.0")
  40.                 .build();
  41.     }
  42. }

给PmsBrandController添加Swagger注解

给原有的品牌管理Controller添加上Swagger注解

  1. package com.macro.mall.tiny.controller;
  3. import com.macro.mall.tiny.common.api.CommonPage;
  4. import com.macro.mall.tiny.common.api.CommonResult;
  5. import com.macro.mall.tiny.mbg.model.PmsBrand;
  6. import com.macro.mall.tiny.service.PmsBrandService;
  7. import io.swagger.annotations.Api;
  8. import io.swagger.annotations.ApiOperation;
  9. import io.swagger.annotations.ApiParam;
  10. import org.slf4j.Logger;
  11. import org.slf4j.LoggerFactory;
  12. import org.springframework.beans.factory.annotation.Autowired;
  13. import org.springframework.stereotype.Controller;
  14. import org.springframework.validation.BindingResult;
  15. import org.springframework.web.bind.annotation.*;
  17. import java.util.List;
  20. /**
  21.  * 品牌管理Controller
  22.  * Created by macro on 2019/4/19.
  23.  */
  24. @Api(tags = "PmsBrandController", description = "商品品牌管理")
  25. @Controller
  26. @RequestMapping("/brand")
  27. public class PmsBrandController {
  28.     @Autowired
  29.     private PmsBrandService brandService;
  31.     private static final Logger LOGGER = LoggerFactory.getLogger(PmsBrandController.class);
  33.     @ApiOperation("获取所有品牌列表")
  34.     @RequestMapping(value = "listAll", method = RequestMethod.GET)
  35.     @ResponseBody
  36.     public CommonResult<List<PmsBrand>> getBrandList() {
  37.         return CommonResult.success(brandService.listAllBrand());
  38.     }
  40.     @ApiOperation("添加品牌")
  41.     @RequestMapping(value = "/create", method = RequestMethod.POST)
  42.     @ResponseBody
  43.     public CommonResult createBrand(@RequestBody PmsBrand pmsBrand) {
  44.         CommonResult commonResult;
  45.         int count = brandService.createBrand(pmsBrand);
  46.         if (count == 1) {
  47.             commonResult = CommonResult.success(pmsBrand);
  48.             LOGGER.debug("createBrand success:{}", pmsBrand);
  49.         } else {
  50.             commonResult = CommonResult.failed("操作失败");
  51.             LOGGER.debug("createBrand failed:{}", pmsBrand);
  52.         }
  53.         return commonResult;
  54.     }
  56.     @ApiOperation("更新指定id品牌信息")
  57.     @RequestMapping(value = "/update/{id}", method = RequestMethod.POST)
  58.     @ResponseBody
  59.     public CommonResult updateBrand(@PathVariable("id") Long id, @RequestBody PmsBrand pmsBrandDto, BindingResult result) {
  60.         CommonResult commonResult;
  61.         int count = brandService.updateBrand(id, pmsBrandDto);
  62.         if (count == 1) {
  63.             commonResult = CommonResult.success(pmsBrandDto);
  64.             LOGGER.debug("updateBrand success:{}", pmsBrandDto);
  65.         } else {
  66.             commonResult = CommonResult.failed("操作失败");
  67.             LOGGER.debug("updateBrand failed:{}", pmsBrandDto);
  68.         }
  69.         return commonResult;
  70.     }
  72.     @ApiOperation("删除指定id的品牌")
  73.     @RequestMapping(value = "/delete/{id}", method = RequestMethod.GET)
  74.     @ResponseBody
  75.     public CommonResult deleteBrand(@PathVariable("id") Long id) {
  76.         int count = brandService.deleteBrand(id);
  77.         if (count == 1) {
  78.             LOGGER.debug("deleteBrand success :id={}", id);
  79.             return CommonResult.success(null);
  80.         } else {
  81.             LOGGER.debug("deleteBrand failed :id={}", id);
  82.             return CommonResult.failed("操作失败");
  83.         }
  84.     }
  86.     @ApiOperation("分页查询品牌列表")
  87.     @RequestMapping(value = "/list", method = RequestMethod.GET)
  88.     @ResponseBody
  89.     public CommonResult<CommonPage<PmsBrand>> listBrand(@RequestParam(value = "pageNum", defaultValue = "1")
  90.                                                         @ApiParam("页码") Integer pageNum,
  91.                                                         @RequestParam(value = "pageSize", defaultValue = "3")
  92.                                                         @ApiParam("每页数量") Integer pageSize) {
  93.         List<PmsBrand> brandList = brandService.listBrand(pageNum, pageSize);
  94.         return CommonResult.success(CommonPage.restPage(brandList));
  95.     }
  97.     @ApiOperation("获取指定id的品牌详情")
  98.     @RequestMapping(value = "/{id}", method = RequestMethod.GET)
  99.     @ResponseBody
  100.     public CommonResult<PmsBrand> brand(@PathVariable("id") Long id) {
  101.         return CommonResult.success(brandService.getBrand(id));
  102.     }
  103. }

修改MyBatis Generator注释的生成规则

CommentGenerator为MyBatis Generator的自定义注释生成器，修改addFieldComment方法使其生成Swagger的@ApiModelProperty注解来取代原来的方法注释，添加addJavaFileComment方法，使其能在import中导入@ApiModelProperty，否则需要手动导入该类，在需要生成大量实体类时，是一件非常麻烦的事。

  1. package com.macro.mall.tiny.mbg;
  3. import org.mybatis.generator.api.IntrospectedColumn;
  4. import org.mybatis.generator.api.IntrospectedTable;
  5. import org.mybatis.generator.api.dom.java.CompilationUnit;
  6. import org.mybatis.generator.api.dom.java.Field;
  7. import org.mybatis.generator.api.dom.java.FullyQualifiedJavaType;
  8. import org.mybatis.generator.internal.DefaultCommentGenerator;
  9. import org.mybatis.generator.internal.util.StringUtility;
  11. import java.util.Properties;
  13. /**
  14.  * 自定义注释生成器
  15.  * Created by macro on 2018/4/26.
  16.  */
  17. public class CommentGenerator extends DefaultCommentGenerator {
  18.     private boolean addRemarkComments = false;
  19.     private static final String EXAMPLE_SUFFIX="Example";
  20.     private static final String API_MODEL_PROPERTY_FULL_CLASS_NAME="io.swagger.annotations.ApiModelProperty";
  22.     /**
  23.      * 设置用户配置的参数
  24.      */
  25.     @Override
  26.     public void addConfigurationProperties(Properties properties) {
  27.         super.addConfigurationProperties(properties);
  28.         this.addRemarkComments = StringUtility.isTrue(properties.getProperty("addRemarkComments"));
  29.     }
  31.     /**
  32.      * 给字段添加注释
  33.      */
  34.     @Override
  35.     public void addFieldComment(Field field, IntrospectedTable introspectedTable,
  36.                                 IntrospectedColumn introspectedColumn) {
  37.         String remarks = introspectedColumn.getRemarks();
  38.         //根据参数和备注信息判断是否添加备注信息
  39.         if(addRemarkComments&&StringUtility.stringHasValue(remarks)){
  40. //            addFieldJavaDoc(field, remarks);
  41.             //数据库中特殊字符需要转义
  42.             if(remarks.contains("\"")){
  43.                 remarks = remarks.replace("\"","'");
  44.             }
  45.             //给model的字段添加swagger注解
  46.             field.addJavaDocLine("@ApiModelProperty(value = \""+remarks+"\")");
  47.         }
  48.     }
  50.     /**
  51.      * 给model的字段添加注释
  52.      */
  53.     private void addFieldJavaDoc(Field field, String remarks) {
  54.         //文档注释开始
  55.         field.addJavaDocLine("/**");
  56.         //获取数据库字段的备注信息
  57.         String[] remarkLines = remarks.split(System.getProperty("line.separator"));
  58.         for(String remarkLine:remarkLines){
  59.             field.addJavaDocLine(" * "+remarkLine);
  60.         }
  61.         addJavadocTag(field, false);
  62.         field.addJavaDocLine(" */");
  63.     }
  65.     @Override
  66.     public void addJavaFileComment(CompilationUnit compilationUnit) {
  67.         super.addJavaFileComment(compilationUnit);
  68.         //只在model中添加swagger注解类的导入
  69.         if(!compilationUnit.isJavaInterface()&&!compilationUnit.getType().getFullyQualifiedName().contains(EXAMPLE_SUFFIX)){
  70.             compilationUnit.addImportedType(new FullyQualifiedJavaType(API_MODEL_PROPERTY_FULL_CLASS_NAME));
  71.         }
  72.     }
  73. }

运行代码生成器重新生成mbg包中的代码

运行com.macro.mall.tiny.mbg.Generator的main方法，重新生成mbg中的代码，可以看到PmsBrand类中已经自动根据数据库注释添加了@ApiModelProperty注解

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

运行项目，查看结果

访问Swagger-UI接口文档地址

接口地址：http://localhost:8080/swagger-ui.html

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

对请求参数已经添加说明

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

对返回结果已经添加说明

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

直接在在线文档上面进行接口测试

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

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

项目源码地址

https://github.com/macrozheng/mall-learning/tree/master/mall-tiny-02