springboot项目整合Swagger-UI实现在线API文档

女爷i 2023-01-08 13:27 144阅读 0赞

**springboot项目整合Swagger-UI实现在线API文档**

> 本文主要讲解是如何通过整合Swagger-UI来实现一份相当完善的在线API文档的。

## 项目使用框架介绍 ##

Swagger-UI  
Swagger-UI是HTML, Javascript, CSS的一个集合，可以动态地根据注解生成在线API文档。

常用注解  
@Api：用于修饰Controller类，生成Controller相关文档信息  
@ApiOperation：用于修饰Controller类中的方法，生成接口方法相关文档信息  
@ApiParam：用于修饰接口中的参数，生成接口参数相关文档信息  
@ApiModelProperty：用于修饰实体类的属性，当实体类是请求参数或返回结果时，直接生成相关文档信息  
整合Swagger-UI  
添加项目依赖  
在pom.xml中新增Swagger-UI相关依赖

<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文档

package com.macro.mall.tiny.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;
    
    /** * Swagger2API文档的配置 */
    @Configuration
    @EnableSwagger2
    public class Swagger2Config { 
        @Bean
        public Docket createRestApi(){ 
            return new Docket(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();
        }
    
        private ApiInfo apiInfo() { 
            return new ApiInfoBuilder()
                    .title("SwaggerUI演示")
                    .description("mall-tiny")
                    .contact("macro")
                    .version("1.0")
                    .build();
        }
    }

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

package com.macro.mall.tiny.controller;

import com.macro.mall.tiny.common.api.CommonPage;  
import com.macro.mall.tiny.common.api.CommonResult;  
import com.macro.mall.tiny.mbg.model.PmsBrand;  
import com.macro.mall.tiny.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.validation.BindingResult;  
import org.springframework.web.bind.annotation.\*;

import java.util.List;

@Api(tags = “PmsBrandController”, description = “商品品牌管理”)  
@Controller  
@RequestMapping("/brand")  
public class PmsBrandController \{  
@Autowired  
private PmsBrandService brandService;

private static final Logger LOGGER = LoggerFactory.getLogger(PmsBrandController.class);
    
        @ApiOperation("获取所有品牌列表")
        @RequestMapping(value = "listAll", method = RequestMethod.GET)
        @ResponseBody
        public CommonResult<List<PmsBrand>> getBrandList() { 
            return CommonResult.success(brandService.listAllBrand());
        }
    
        @ApiOperation("添加品牌")
        @RequestMapping(value = "/create", method = RequestMethod.POST)
        @ResponseBody
        public CommonResult createBrand(@RequestBody PmsBrand pmsBrand) { 
            CommonResult commonResult;
            int count = brandService.createBrand(pmsBrand);
            if (count == 1) { 
                commonResult = CommonResult.success(pmsBrand);
                LOGGER.debug("createBrand success:{}", pmsBrand);
            } else { 
                commonResult = CommonResult.failed("操作失败");
                LOGGER.debug("createBrand failed:{}", pmsBrand);
            }
            return commonResult;
        }
    
        @ApiOperation("更新指定id品牌信息")
        @RequestMapping(value = "/update/{id}", method = RequestMethod.POST)
        @ResponseBody
        public CommonResult updateBrand(@PathVariable("id") Long id, @RequestBody PmsBrand pmsBrandDto, BindingResult result) { 
            CommonResult commonResult;
            int count = 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);
            }
            return commonResult;
        }
    
        @ApiOperation("删除指定id的品牌")
        @RequestMapping(value = "/delete/{id}", method = RequestMethod.GET)
        @ResponseBody
        public CommonResult deleteBrand(@PathVariable("id") Long id) { 
            int count = brandService.deleteBrand(id);
            if (count == 1) { 
                LOGGER.debug("deleteBrand success :id={}", id);
                return CommonResult.success(null);
            } else { 
                LOGGER.debug("deleteBrand failed :id={}", id);
                return CommonResult.failed("操作失败");
            }
        }
    
        @ApiOperation("分页查询品牌列表")
        @RequestMapping(value = "/list", method = RequestMethod.GET)
        @ResponseBody
        public CommonResult<CommonPage<PmsBrand>> listBrand(@RequestParam(value = "pageNum", defaultValue = "1")
                                                            @ApiParam("页码") Integer pageNum,
                                                            @RequestParam(value = "pageSize", defaultValue = "3")
                                                            @ApiParam("每页数量") Integer pageSize) { 
            List<PmsBrand> brandList = brandService.listBrand(pageNum, pageSize);
            return CommonResult.success(CommonPage.restPage(brandList));
        }
    
        @ApiOperation("获取指定id的品牌详情")
        @RequestMapping(value = "/{id}", method = RequestMethod.GET)
        @ResponseBody
        public CommonResult<PmsBrand> brand(@PathVariable("id") Long id) { 
            return CommonResult.success(brandService.getBrand(id));
        }
    }

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

package com.macro.mall.tiny.mbg;
    
    import org.mybatis.generator.api.IntrospectedColumn;
    import org.mybatis.generator.api.IntrospectedTable;
    import org.mybatis.generator.api.dom.java.CompilationUnit;
    import org.mybatis.generator.api.dom.java.Field;
    import org.mybatis.generator.api.dom.java.FullyQualifiedJavaType;
    import org.mybatis.generator.internal.DefaultCommentGenerator;
    import org.mybatis.generator.internal.util.StringUtility;
    
    import java.util.Properties;
    
    /** * 自定义注释生成器 * Created by macro on 2018/4/26. */
    public class CommentGenerator extends DefaultCommentGenerator { 
        private boolean addRemarkComments = false;
        private static final String EXAMPLE_SUFFIX="Example";
        private static final String API_MODEL_PROPERTY_FULL_CLASS_NAME="io.swagger.annotations.ApiModelProperty";
    
        /** * 设置用户配置的参数 */
        @Override
        public void addConfigurationProperties(Properties properties) { 
            super.addConfigurationProperties(properties);
            this.addRemarkComments = StringUtility.isTrue(properties.getProperty("addRemarkComments"));
        }
    
        /** * 给字段添加注释 */
        @Override
        public void addFieldComment(Field field, IntrospectedTable introspectedTable,
                                    IntrospectedColumn introspectedColumn) { 
            String remarks = introspectedColumn.getRemarks();
            //根据参数和备注信息判断是否添加备注信息
            if(addRemarkComments&&StringUtility.stringHasValue(remarks)){ 
    // addFieldJavaDoc(field, remarks);
                //数据库中特殊字符需要转义
                if(remarks.contains("\"")){ 
                    remarks = remarks.replace("\"","'");
                }
                //给model的字段添加swagger注解
                field.addJavaDocLine("@ApiModelProperty(value = \""+remarks+"\")");
            }
        }
    
        /** * 给model的字段添加注释 */
        private void addFieldJavaDoc(Field field, String remarks) { 
            //文档注释开始
            field.addJavaDocLine("/**");
            //获取数据库字段的备注信息
            String[] remarkLines = remarks.split(System.getProperty("line.separator"));
            for(String remarkLine:remarkLines){ 
                field.addJavaDocLine(" * "+remarkLine);
            }
            addJavadocTag(field, false);
            field.addJavaDocLine(" */");
        }
    
        @Override
        public void addJavaFileComment(CompilationUnit compilationUnit) { 
            super.addJavaFileComment(compilationUnit);
            //只在model中添加swagger注解类的导入
            if(!compilationUnit.isJavaInterface()&&!compilationUnit.getType().getFullyQualifiedName().contains(EXAMPLE_SUFFIX)){ 
                compilationUnit.addImportedType(new FullyQualifiedJavaType(API_MODEL_PROPERTY_FULL_CLASS_NAME));
            }
        }
    }

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

运行项目，查看结果  
访问Swagger-UI接口文档地址  
接口地址：http://localhost:8080/swagger-ui.html

![在这里插入图片描述][watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L3dlaXhpbl80NDMwMjI0MA_size_16_color_FFFFFF_t_70]

对请求参数已经添加说明  
![在这里插入图片描述][watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L3dlaXhpbl80NDMwMjI0MA_size_16_color_FFFFFF_t_70 1]

对返回结果已![在这里插入图片描述][watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L3dlaXhpbl80NDMwMjI0MA_size_16_color_FFFFFF_t_70 2]  
经添加说明

直接在在线文档上面进行接口测试  
![在这里插入图片描述][watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L3dlaXhpbl80NDMwMjI0MA_size_16_color_FFFFFF_t_70 3]

[watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L3dlaXhpbl80NDMwMjI0MA_size_16_color_FFFFFF_t_70]: /images/20221119/0346ab67584647c185190579f5e1775a.png
[watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L3dlaXhpbl80NDMwMjI0MA_size_16_color_FFFFFF_t_70 1]: /images/20221119/d58f6c79e4de4d8bab5d60768126d66a.png
[watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L3dlaXhpbl80NDMwMjI0MA_size_16_color_FFFFFF_t_70 2]: /images/20221119/f9288bbc349a4308954099802c5f2223.png
[watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L3dlaXhpbl80NDMwMjI0MA_size_16_color_FFFFFF_t_70 3]: /images/20221119/16499a1788cc4185beb66f11e51a2103.png