本文主要讲解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;

2. 
   

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;

12. 
    

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. }

33. 
    

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;

2. 
   

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.*;

16. 
    

17. import java.util.List;

18. 
    

19. 
    

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;

30. 
    

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

32. 
    

33. @ApiOperation("获取所有品牌列表")

34. @RequestMapping(value = "listAll", method = RequestMethod.GET)

35. @ResponseBody

36. public CommonResult<List<PmsBrand>> getBrandList() {

37. return CommonResult.success(brandService.listAllBrand());

38. }

39. 
    

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. }

55. 
    

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. }

71. 
    

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. }

85. 
    

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. }

96. 
    

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;

2. 
   

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;

10. 
    

11. import java.util.Properties;

12. 
    

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";

21. 
    

22. /**

23. * 设置用户配置的参数

24. */

25. @Override

26. public void addConfigurationProperties(Properties properties) {

27. super.addConfigurationProperties(properties);

28. this.addRemarkComments = StringUtility.isTrue(properties.getProperty("addRemarkComments"));

29. }

30. 
    

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. }

49. 
    

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. }

64. 
    

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注解

运行项目，查看结果

访问Swagger-UI接口文档地址

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

对请求参数已经添加说明

对返回结果已经添加说明

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

项目源码地址

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

推荐阅读

• mall架构及功能概览

• mall学习所需知识点（推荐资料）

• mall整合SpringBoot+MyBatis搭建基本骨架

欢迎关注，点个在看