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

2024-01-15 22:33:10

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

<!--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>

添加Swagger-UI的配置

添加Swagger-UI的Java配置文件

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

  • 生成指定包下面的类的API文档

  • 生成有指定注解的类的API文档

  • 生成有指定注解的方法的API文档



    

  1. package com.macro.mall.tiny.config;
    2. 


    3. 

  3. import org.springframework.context.annotation.Bean;
    4. 

  4. import org.springframework.context.annotation.Configuration;
    5. 

  5. import springfox.documentation.builders.ApiInfoBuilder;
    6. 

  6. import springfox.documentation.builders.PathSelectors;
    7. 

  7. import springfox.documentation.builders.RequestHandlerSelectors;
    8. 

  8. import springfox.documentation.service.ApiInfo;
    9. 

  9. import springfox.documentation.spi.DocumentationType;
    10. 

  10. import springfox.documentation.spring.web.plugins.Docket;
    11. 

  11. import springfox.documentation.swagger2.annotations.EnableSwagger2;
    12. 


    13. 

  13. /**
    14. 

  14.  * Swagger2API文档的配置
    15. 

  15.  */
    16. 

  16. @Configuration
    17. 

  17. @EnableSwagger2
    18. 

  18. public class Swagger2Config {
    19. 

  19.     @Bean
    20. 

  20.     public Docket createRestApi(){
    21. 

  21.         return new Docket(DocumentationType.SWAGGER_2)
    22. 

  22.                 .apiInfo(apiInfo())
    23. 

  23.                 .select()
    24. 

  24.                 //为当前包下controller生成API文档
    25. 

  25.                 .apis(RequestHandlerSelectors.basePackage("com.macro.mall.tiny.controller"))
    26. 

  26.                 //为有@Api注解的Controller生成API文档
    27. 

  27. //                .apis(RequestHandlerSelectors.withClassAnnotation(Api.class))
    28. 

  28.                 //为有@ApiOperation注解的方法生成API文档
    29. 

  29. //                .apis(RequestHandlerSelectors.withMethodAnnotation(ApiOperation.class))
    30. 

  30.                 .paths(PathSelectors.any())
    31. 

  31.                 .build();
    32. 

  32.     }
    33. 


    34. 

  34.     private ApiInfo apiInfo() {
    35. 

  35.         return new ApiInfoBuilder()
    36. 

  36.                 .title("SwaggerUI演示")
    37. 

  37.                 .description("mall-tiny")
    38. 

  38.                 .contact("macro")
    39. 

  39.                 .version("1.0")
    40. 

  40.                 .build();
    41. 

  41.     }
    42. 

  42. }
    43. 



给PmsBrandController添加Swagger注解


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




    

  1. package com.macro.mall.tiny.controller;
    2. 


    3. 

  3. import com.macro.mall.tiny.common.api.CommonPage;
    4. 

  4. import com.macro.mall.tiny.common.api.CommonResult;
    5. 

  5. import com.macro.mall.tiny.mbg.model.PmsBrand;
    6. 

  6. import com.macro.mall.tiny.service.PmsBrandService;
    7. 

  7. import io.swagger.annotations.Api;
    8. 

  8. import io.swagger.annotations.ApiOperation;
    9. 

  9. import io.swagger.annotations.ApiParam;
    10. 

  10. import org.slf4j.Logger;
    11. 

  11. import org.slf4j.LoggerFactory;
    12. 

  12. import org.springframework.beans.factory.annotation.Autowired;
    13. 

  13. import org.springframework.stereotype.Controller;
    14. 

  14. import org.springframework.validation.BindingResult;
    15. 

  15. import org.springframework.web.bind.annotation.*;
    16. 


    17. 

  17. import java.util.List;
    18. 


    19. 


    20. 

  20. /**
    21. 

  21.  * 品牌管理Controller
    22. 

  22.  * Created by macro on 2019/4/19.
    23. 

  23.  */
    24. 

  24. @Api(tags = "PmsBrandController", description = "商品品牌管理")
    25. 

  25. @Controller
    26. 

  26. @RequestMapping("/brand")
    27. 

  27. public class PmsBrandController {
    28. 

  28.     @Autowired
    29. 

  29.     private PmsBrandService brandService;
    30. 


    31. 

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


    33. 

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

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

  35.     @ResponseBody
    36. 

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

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

  38.     }
    39. 


    40. 

  40.     @ApiOperation("添加品牌")
    41. 

  41.     @RequestMapping(value = "/create", method = RequestMethod.POST)
    42. 

  42.     @ResponseBody
    43. 

  43.     public CommonResult createBrand(@RequestBody PmsBrand pmsBrand) {
    44. 

  44.         CommonResult commonResult;
    45. 

  45.         int count = brandService.createBrand(pmsBrand);
    46. 

  46.         if (count == 1) {
    47. 

  47.             commonResult = CommonResult.success(pmsBrand);
    48. 

  48.             LOGGER.debug("createBrand success:{}", pmsBrand);
    49. 

  49.         } else {
    50. 

  50.             commonResult = CommonResult.failed("操作失败");
    51. 

  51.             LOGGER.debug("createBrand failed:{}", pmsBrand);
    52. 

  52.         }
    53. 

  53.         return commonResult;
    54. 

  54.     }
    55. 


    56. 

  56.     @ApiOperation("更新指定id品牌信息")
    57. 

  57.     @RequestMapping(value = "/update/{id}", method = RequestMethod.POST)
    58. 

  58.     @ResponseBody
    59. 

  59.     public CommonResult updateBrand(@PathVariable("id") Long id, @RequestBody PmsBrand pmsBrandDto, BindingResult result) {
    60. 

  60.         CommonResult commonResult;
    61. 

  61.         int count = brandService.updateBrand(id, pmsBrandDto);
    62. 

  62.         if (count == 1) {
    63. 

  63.             commonResult = CommonResult.success(pmsBrandDto);
    64. 

  64.             LOGGER.debug("updateBrand success:{}", pmsBrandDto);
    65. 

  65.         } else {
    66. 

  66.             commonResult = CommonResult.failed("操作失败");
    67. 

  67.             LOGGER.debug("updateBrand failed:{}", pmsBrandDto);
    68. 

  68.         }
    69. 

  69.         return commonResult;
    70. 

  70.     }
    71. 


    72. 

  72.     @ApiOperation("删除指定id的品牌")
    73. 

  73.     @RequestMapping(value = "/delete/{id}", method = RequestMethod.GET)
    74. 

  74.     @ResponseBody
    75. 

  75.     public CommonResult deleteBrand(@PathVariable("id") Long id) {
    76. 

  76.         int count = brandService.deleteBrand(id);
    77. 

  77.         if (count == 1) {
    78. 

  78.             LOGGER.debug("deleteBrand success :id={}", id);
    79. 

  79.             return CommonResult.success(null);
    80. 

  80.         } else {
    81. 

  81.             LOGGER.debug("deleteBrand failed :id={}", id);
    82. 

  82.             return CommonResult.failed("操作失败");
    83. 

  83.         }
    84. 

  84.     }
    85. 


    86. 

  86.     @ApiOperation("分页查询品牌列表")
    87. 

  87.     @RequestMapping(value = "/list", method = RequestMethod.GET)
    88. 

  88.     @ResponseBody
    89. 

  89.     public CommonResult<CommonPage<PmsBrand>> listBrand(@RequestParam(value = "pageNum", defaultValue = "1")
    90. 

  90.                                                         @ApiParam("页码") Integer pageNum,
    91. 

  91.                                                         @RequestParam(value = "pageSize", defaultValue = "3")
    92. 

  92.                                                         @ApiParam("每页数量") Integer pageSize) {
    93. 

  93.         List<PmsBrand> brandList = brandService.listBrand(pageNum, pageSize);
    94. 

  94.         return CommonResult.success(CommonPage.restPage(brandList));
    95. 

  95.     }
    96. 


    97. 

  97.     @ApiOperation("获取指定id的品牌详情")
    98. 

  98.     @RequestMapping(value = "/{id}", method = RequestMethod.GET)
    99. 

  99.     @ResponseBody
    100. 

  100.     public CommonResult<PmsBrand> brand(@PathVariable("id") Long id) {
    101. 

  101.         return CommonResult.success(brandService.getBrand(id));
    102. 

  102.     }
    103. 

  103. }
    104. 



修改MyBatis Generator注释的生成规则


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




    

  1. package com.macro.mall.tiny.mbg;
    2. 


    3. 

  3. import org.mybatis.generator.api.IntrospectedColumn;
    4. 

  4. import org.mybatis.generator.api.IntrospectedTable;
    5. 

  5. import org.mybatis.generator.api.dom.java.CompilationUnit;
    6. 

  6. import org.mybatis.generator.api.dom.java.Field;
    7. 

  7. import org.mybatis.generator.api.dom.java.FullyQualifiedJavaType;
    8. 

  8. import org.mybatis.generator.internal.DefaultCommentGenerator;
    9. 

  9. import org.mybatis.generator.internal.util.StringUtility;
    10. 


    11. 

  11. import java.util.Properties;
    12. 


    13. 

  13. /**
    14. 

  14.  * 自定义注释生成器
    15. 

  15.  * Created by macro on 2018/4/26.
    16. 

  16.  */
    17. 

  17. public class CommentGenerator extends DefaultCommentGenerator {
    18. 

  18.     private boolean addRemarkComments = false;
    19. 

  19.     private static final String EXAMPLE_SUFFIX="Example";
    20. 

  20.     private static final String API_MODEL_PROPERTY_FULL_CLASS_NAME="io.swagger.annotations.ApiModelProperty";
    21. 


    22. 

  22.     /**
    23. 

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

  24.      */
    25. 

  25.     @Override
    26. 

  26.     public void addConfigurationProperties(Properties properties) {
    27. 

  27.         super.addConfigurationProperties(properties);
    28. 

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

  29.     }
    30. 


    31. 

  31.     /**
    32. 

  32.      * 给字段添加注释
    33. 

  33.      */
    34. 

  34.     @Override
    35. 

  35.     public void addFieldComment(Field field, IntrospectedTable introspectedTable,
    36. 

  36.                                 IntrospectedColumn introspectedColumn) {
    37. 

  37.         String remarks = introspectedColumn.getRemarks();
    38. 

  38.         //根据参数和备注信息判断是否添加备注信息
    39. 

  39.         if(addRemarkComments&&StringUtility.stringHasValue(remarks)){
    40. 

  40. //            addFieldJavaDoc(field, remarks);
    41. 

  41.             //数据库中特殊字符需要转义
    42. 

  42.             if(remarks.contains("\"")){
    43. 

  43.                 remarks = remarks.replace("\"","'");
    44. 

  44.             }
    45. 

  45.             //给model的字段添加swagger注解
    46. 

  46.             field.addJavaDocLine("@ApiModelProperty(value = \""+remarks+"\")");
    47. 

  47.         }
    48. 

  48.     }
    49. 


    50. 

  50.     /**
    51. 

  51.      * 给model的字段添加注释
    52. 

  52.      */
    53. 

  53.     private void addFieldJavaDoc(Field field, String remarks) {
    54. 

  54.         //文档注释开始
    55. 

  55.         field.addJavaDocLine("/**");
    56. 

  56.         //获取数据库字段的备注信息
    57. 

  57.         String[] remarkLines = remarks.split(System.getProperty("line.separator"));
    58. 

  58.         for(String remarkLine:remarkLines){
    59. 

  59.             field.addJavaDocLine(" * "+remarkLine);
    60. 

  60.         }
    61. 

  61.         addJavadocTag(field, false);
    62. 

  62.         field.addJavaDocLine(" */");
    63. 

  63.     }
    64. 


    65. 

  65.     @Override
    66. 

  66.     public void addJavaFileComment(CompilationUnit compilationUnit) {
    67. 

  67.         super.addJavaFileComment(compilationUnit);
    68. 

  68.         //只在model中添加swagger注解类的导入
    69. 

  69.         if(!compilationUnit.isJavaInterface()&&!compilationUnit.getType().getFullyQualifiedName().contains(EXAMPLE_SUFFIX)){
    70. 

  70.             compilationUnit.addImportedType(new FullyQualifiedJavaType(API_MODEL_PROPERTY_FULL_CLASS_NAME));
    71. 

  71.         }
    72. 

  72.     }
    73. 

  73. }
    74. 



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


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




运行项目，查看结果


访问Swagger-UI接口文档地址


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




对请求参数已经添加说明




对返回结果已经添加说明


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


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


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


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





 

上一篇：SpringBoot(7) ------>整合Elasticsearch

下一篇：PC禁止浏览器缩放