Springboot项目整合SpringDoc实现在线API文档

项目集成SpringDoc

• 首先我们需要在pom.xml文件中添加SpringDoc的依赖；

<!--SpringDoc相关依赖-->
<dependency>
    <groupId>org.springdoc</groupId>
    <artifactId>springdoc-openapi-starter-webmvc-ui</artifactId>
    <version>${springdoc-openapi.version}</version>
</dependency>

• 然后修改application.yml配置文件，添加SpringDoc的配置，这里我对项目中的接口进行了划分，划分为了mall-admin、mall-portal和mall-search三个组，之后我们将会把mall-tiny拆分为这三个微服务；

springdoc:
  swagger-ui:
    # 修改Swagger UI路径
    path: /swagger-ui.html
    # 开启Swagger UI界面
    enabled: true
  api-docs:
    # 修改api-docs路径
    path: /v3/api-docs
    # 开启api-docs
    enabled: true
  group-configs:
    - group: 'mall-admin'
      paths-to-match:
        - '/brand/**'
        - '/minio/**'
        - '/admin/**'
      packages-to-scan: com.macro.mall.tiny.controller
    - group: 'mall-portal'
      paths-to-match:
        - '/order/**'
        - '/sso/**'
        - '/member/**'
      packages-to-scan: com.macro.mall.tiny.controller
    - group: 'mall-search'
      paths-to-match:
        - '/esProduct/**'
      packages-to-scan: com.macro.mall.tiny.controller
  default-flat-param-object: false

• 之后添加SpringDoc的Java配置，主要是添加一些API文档的基本信息；

/**
 * @auther macrozheng
 * @description SpringDoc API文档相关配置
 * @date 2022/3/4
 * @github https://github.com/macrozheng
 */
@Configuration
public class SpringDocConfig {

    @Bean
    public OpenAPI mallTinyOpenAPI() {
        return new OpenAPI()
                .info(new Info().title("Mall-Tiny API")
                        .description("SpringDoc API 演示")
                        .version("v1.0.0")
                        .license(new License().name("Apache 2.0").url("https://github.com/macrozheng/mall-learning")))
                .externalDocs(new ExternalDocumentation()
                        .description("SpringBoot实战电商项目mall（50K+Star）全套文档")
                        .url("http://www.macrozheng.com"));
    }

}

• 之后给controller包中的接口添加SpringDoc提供的@Tag、@Operation等注解，主要是给接口类和接口方法添加说明，这里以UmsAdminController为例。

/**
 * @auther macrozheng
 * @description 后台用户管理
 * @date 2018/4/26
 * @github https://github.com/macrozheng
 */
@Controller
@Tag(name = "UmsAdminController", description = "后台用户管理")
@RequestMapping("/admin")
public class UmsAdminController {
    @Autowired
    private UmsAdminService adminService;
    @Value("${jwt.tokenHeader}")
    private String tokenHeader;
    @Value("${jwt.tokenHead}")
    private String tokenHead;

    @Operation(summary = "登录以后返回token")
    @RequestMapping(value = "/login", method = RequestMethod.POST)
    @ResponseBody
    public CommonResult login(@RequestParam String username, @RequestParam String password) {
        String token = adminService.login(username, password);
        if (token == null) {
            return CommonResult.validateFailed("用户名或密码错误");
        }
        Map<String, String> tokenMap = new HashMap<>();
        tokenMap.put("token", token);
        tokenMap.put("tokenHead", tokenHead);
        return CommonResult.success(tokenMap);
    }

    @Operation(summary = "获取所有资源列表")
    @RequestMapping(value = "/resourceList", method = RequestMethod.POST)
    @ResponseBody
    public CommonResult<List<UmsResource>> resourceList() {
        List<UmsResource> resourceList = adminService.getResourceList();
        return CommonResult.success(resourceList);
    }
}

代码生成器集成SpringDoc

由于我们的实体类是用MyBatis Generator代码生成器生成的，如果我们想给实体类添加说明，还需要在代码生成器生成实体类的同时生成SpringDoc的注解。

• 我们需要在CommentGenerator类中，给生成的实体类导入@Schema注解，根据数据库中的字段注释给实体类添加@Schema说明；

/**
 * @auther macrozheng
 * @description 自定义注释生成器
 * @date 2018/4/26
 * @github https://github.com/macrozheng
 */
public class CommentGenerator extends DefaultCommentGenerator {
    private boolean addRemarkComments = false;
    private static final String EXAMPLE_SUFFIX="Example";
    private static final String MAPPER_SUFFIX="Mapper";
    private static final String API_MODEL_PROPERTY_FULL_CLASS_NAME="io.swagger.v3.oas.annotations.media.Schema";

    /**
     * 设置用户配置的参数
     */
    @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();
        //根据参数和备注信息判断是否添加swagger注解信息
        if(addRemarkComments&&StringUtility.stringHasValue(remarks)){
//            addFieldJavaDoc(field, remarks);
            //数据库中特殊字符需要转义
            if(remarks.contains("\"")){
                remarks = remarks.replace("\"","'");
            }
            //给model的字段添加swagger注解
            field.addJavaDocLine("@Schema(title = \""+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.getType().getFullyQualifiedName().contains(MAPPER_SUFFIX)&&!compilationUnit.getType().getFullyQualifiedName().contains(EXAMPLE_SUFFIX)){
            compilationUnit.addImportedType(new FullyQualifiedJavaType(API_MODEL_PROPERTY_FULL_CLASS_NAME));
        }
    }
}

• 之后我们运行Generator类的main方法生成代码时，就会在实体类上直接添加SpringDoc的@Schema注解了。

public class PmsBrand implements Serializable {
    private Long id;

    private String name;

    @Schema(title = "首字母")
    private String firstLetter;

    private Integer sort;

    @Schema(title = "是否为品牌制造商：0->不是；1->是")
    private Integer factoryStatus;

    private Integer showStatus;

    @Schema(title = "产品数量")
    private Integer productCount;

    @Schema(title = "产品评论数量")
    private Integer productCommentCount;

    @Schema(title = "品牌logo")
    private String logo;

    @Schema(title = "专区大图")
    private String bigPic;

    @Schema(title = "品牌故事")
    private String brandStory;

    //省略若干代码...
}

测试

集成SpringDoc之后，我们直接运行启动类的main方法来运行项目，就可以访问项目的API文档页了：http://localhost:8080/swagger-ui/index.html

总结

本节课程主要讲解了mall-tiny脚手架项目中集成SpringDoc的方式，大家只要掌握SpringDoc使用，集成起来还是没啥难度的。

项目源码地址

https://github.com/macrozheng/mall-swarm-arch/tree/master/mall-tiny