当前位置： 首页 > news >正文

猿创征文｜小而巧的API文档生成工具之smart-doc

news 来源：原创 2024/5/2 2:47:51

文章目录

  • smart-doc介绍
  • smart-doc特性
  • smart-doc的最佳搭档
  • 谁在使用smart-doc
  • smart-doc的优缺点
  • smart-doc和swagger区别比较
  • smart-doc的使用姿势
    • 姿势一
    • 姿势二
    • 姿势三（公司内部推荐使用）
  • 总结

smart-doc介绍

一个 java restful api 文档生成工具，不用像Swagger一样写大量注解，完全基于接口源码分析来生成接口文档，但是需要按照 java的标准注释写。

完全基于接口源码来分析生成接口文档，不采用任何注解侵入到业务代码中。

你只需要按照java-doc标准编写注释， smart-doc就能帮你生成一个简易明了的Markdown、HTML5、Postman ollection2.0+、OpenAPI 3.0+的文档。

注意：需要完全按照java的标准注释，如果方法注释包含特殊符号或者换行的话，生成的json是会出现格式错误，但是不影响相关的html使用。

smart-doc特性

  • 零注解、零学习成本、只需要写标准JAVA注释。
  • 基于源代码接口定义自动推导，强大的返回结构推导。
  • 支持Spring MVC、Spring Boot、Spring Boot Web Flux(Controller书写方式)Feign。
  • 支持Callable、Future、CompletableFuture等异步接口返回的推导。
  • 支持JavaBean上的JSR303参数校验规范，包括分组验证。
  • 对JSON请求参数的接口能够自动生成模拟JSON参数。
  • 对一些常用字段定义能够生成有效的模拟值。
  • 支持生成JSON返回值示例。
  • 支持从项目外部加载源代码来生成字段注释(包括标准规范发布的jar包)。
  • 支持生成多种格式文档：Markdown、HTML5、Asciidoctor、Postman Collection、OpenAPI 3.0。 开放文档数据，可自由实现接入文档管理系统。
  • 支持导出错误码和定义在代码中的各种字典码到接口文档。
  • 支持Maven、Gradle插件式轻松集成。
  • 支持Apache Dubbo RPC接口文档生成。
  • debug接口调试html5页面完全支持文件上传，下载(@download tag标记下载方法)测试。

smart-doc的最佳搭档

smart-doc + Torna 组成的文档生成和管理解决方案，使用smart-doc无侵入完成JAVA源代码分析和提取注释生成API文档，自动将文档推送到Torna企业级接口文档管理平台。

小而巧的API文档生成工具之smart-doc - Java技术债务

谁在使用smart-doc

小而巧的API文档生成工具之smart-doc - Java技术债务

smart-doc的优缺点

简单总结了几个特别明显以及我认为最关键的几个优点如下：

  • 非侵入式接口文档生成
  • 需要按照java文档注释规范对接口及相关对象添加注释
  • 编译文件后需要手动运行插件生成接口文档
  • 配置简单，只需要引入插件，配置文档输出位置即可。相关更加复杂的配置根据需要自行配置。
  • 无需启动项目，生成文档后可直接浏览

缺点
我总结了一下我使用过程中的缺点，在此我仅代表我自己提出的缺点如下

  • 生成的openapi.json数据时，不支持泛型的多层嵌套解析，导致不同接口的responseBody解析为一个。比如接口返回为：ResultVO<DefinePage<AiOptimizationCampaignReportVO>>，解析成ResultVODefinePage（新版本已解决）

smart-doc和swagger区别比较

功能特性smart-docswagger
代码侵入无注解侵入性严重
集成复杂度简单，只需插件偏复杂
插件支持有 gradle 和 maven 插件无插件
openapi 规范支持支持 openapi 3.0完全支持 openapi 的版本
CI 构建集成可在 ci 构建阶段使用maven 或者 gradle 命令启动插件生成文档不支持
集中化文档中心集成已经和 torna 企业级接口文档管理平台对接不支持
维护持续性值得信赖，开源后用户基础多，一直持续维护全球用户多，开源维护值得信赖
接口 debug2.0.0 版本开始已经支持 debug，页面比 swagger 漂亮太多了。支持

Smart-doc 从 2.0.0 后几乎实现了 swagger ui 的功能，并且比 swagger ui 更简洁大方，也更符合国内开发者的诉求。当然 smart-doc 的功能也已经超过了 swagger 为 java 开发者提供的功能。当然 smart-doc 本身是只支持扫描代码生成 openapi 3.0 的文档的，也可以将生成的 openapi 3.0 文档导入到其他 ui 中渲染展示。

swagger 生成 离线的文档 需要借助第三方jar包实现，而 smart-doc 直接 运行 test 方法就可以直接导出 md，html，asciidoc 等格式文档。

设计思路不同，smart-doc 是基于 源码分析的，它生成api文档是通过分析JAVA源码主要是通过 注释 和 系统自带注解，来实现文档的 生成，而 swagger 是运行时 自动生成在线文档，并且 生成 测试 接口的 案例。由于他们设计思路 理念 不一样，swagger2 使用过程需要使用它定义的@API 相关注解，这样就污染了源码，代码入侵有点高，而smart -doc 就不一样了，主要是通过 注释 、解析/** */ 来生成API文档的 。这样基本上没有入侵性，很自由！

swagger

  • 侵入式接口文档生成
  • 每个接口及每个实体类都需要添加注解
  • 配置复杂，需要添加依赖然后需要添加相关配置
  • 编译后自动生成接口文档
  • 需要启动后才能查看，如果配置了安全框架还需要开放相关接口

smart-doc的使用姿势

姿势一

使用maven或者gradle插件进行一键生成对应的文档格式或者命令进行生成，在这里我只展示了maven插件的使用姿势。

<plugin>
    <groupId>com.github.shalousun</groupId>
    <artifactId>smart-doc-maven-plugin</artifactId>
    <version>2.4.9</version>
    <configuration>
        <!--指定生成文档的使用的配置文件,配置文件放在自己的项目中-->
        <configFile>./src/main/resources/smart-doc.json</configFile>
        <!--指定项目名称-->
        <projectName>测试</projectName>
        <!--smart-doc实现自动分析依赖树加载第三方依赖的源码，如果一些框架依赖库加载不到导致报错，这时请使用excludes排除掉-->
        <excludes>
            <!--格式为：groupId:artifactId;参考如下-->
            <!--也可以支持正则式如：com.alibaba:.* -->
            <exclude>com.alibaba:fastjson</exclude>
        </excludes>
        <!--includes配置用于配置加载外部依赖源码,配置后插件会按照配置项加载外部源代码而不是自动加载所有，因此使用时需要注意-->
        <!--smart-doc能自动分析依赖树加载所有依赖源码，原则上会影响文档构建效率，因此你可以使用includes来让插件加载你配置的组件-->
        <includes>
            <!--格式为：groupId:artifactId;参考如下-->
            <!--也可以支持正则式如：com.alibaba:.* -->
            <include>com.alibaba:fastjson</include>
            <!-- 如果配置了includes的情况下， 使用了mybatis-plus的分页需要include所使用的源码包 -->
            <include>com.baomidou:mybatis-plus-extension</include>
            <!-- 如果配置了includes的情况下， 使用了jpa的分页需要include所使用的源码包 -->
            <include>org.springframework.data:spring-data-commons</include>
        </includes>
    </configuration>
    <executions>
        <execution>
            <!--如果不需要在执行编译时启动smart-doc，则将phase注释掉-->
            <phase>compile</phase>
            <goals>
                <!--smart-doc提供了html、openapi、markdown等goal，可按需配置-->
                <goal>html</goal>
            </goals>
        </execution>
    </executions>
</plugin>

如果配置<phase>clean|validate|compile|test|package|verify|install|site|deploy</phase>这些，可以在以上指令被触发时执行smart-doc文档生成

使用maven插件命令如下：

//生成html
mvn -Dfile.encoding=UTF-8 smart-doc:html
//生成markdown
mvn -Dfile.encoding=UTF-8 smart-doc:markdown
//生成adoc
mvn -Dfile.encoding=UTF-8 smart-doc:adoc
//生成postman json数据
mvn -Dfile.encoding=UTF-8 smart-doc:postman
// 生成 Open Api 3.0+,Since smart-doc-maven-plugin 1.1.5
mvn -Dfile.encoding=UTF-8 smart-doc:openapi
// 生成文档推送到Torna平台
mvn -Dfile.encoding=UTF-8 smart-doc:torna-rest

// Apache Dubbo RPC文档
// Generate html
mvn -Dfile.encoding=UTF-8 smart-doc:rpc-html
// Generate markdown
mvn -Dfile.encoding=UTF-8 smart-doc:rpc-markdown
// Generate adoc
mvn -Dfile.encoding=UTF-8 smart-doc:rpc-adoc

// 生成dubbo接口文档推送到torna
mvn -Dfile.encoding=UTF-8 smart-doc:torna-rpc

使用IDE一键生成如下：

小而巧的API文档生成工具之smart-doc - Java技术债务

优点：便捷，快速上手

缺点：每个服务各自指定smart-doc的配置文件smart-doc.json

姿势二

导入相关smart-doc依赖

<!--导入Smart-doc依赖-->
<dependency>
    <groupId>com.github.shalousun</groupId>
    <artifactId>smart-doc</artifactId>
    <version>2.5.1</version>
</dependency>

手动为每个项目引入以上jar包，可以使用smart-doc.json配置文件也可以使用smart-doc自带的ApiConfig配置类进行手动配置。

使用单元测试测试API文档生成如下：

@Test
public void testBuilderControllersApi() {
    ApiConfig config = new ApiConfig();
    config.setServerUrl("http://localhost:8080");
    //当把AllInOne设置为true时，Smart-doc将会把所有接口生成到一个Markdown、HHTML或者AsciiDoc中
    config.setAllInOne(true);

    //HTML5文档，建议直接放到src/main/resources/static/doc下，Smart-doc提供一个配置常量HTML_DOC_OUT_PATH
    //源码---String HTML_DOC_OUT_PATH = "src/main/resources/static/doc";
    config.setOutPath("src/main/resources/static/doc");

    // 设置接口包扫描路径过滤，如果不配置则Smart-doc默认扫描所有的接口类
    // 配置多个报名有英文逗号隔开
    config.setPackageFilters("com.***.Controller.*");

    //设置错误错列表，遍历自己的错误码设置给Smart-doc即可
    List<ApiErrorCode> errorCodeList = new ArrayList<>();
    for (HttpCodeEnum codeEnum : HttpCodeEnum.values()) {
        ApiErrorCode errorCode = new ApiErrorCode();
        errorCode.setValue(codeEnum.getCode()).setDesc(codeEnum.getMessage());
        errorCodeList.add(errorCode);
    }

    //不需要显示错误码,则可以不用设置错误码。
    config.setErrorCodes(errorCodeList);
    //生成Markdown文件
    HtmlApiDocBuilder.buildApiDoc(config);
}

姿势三（公司内部推荐使用）

Q：为什么说公司内部建议使用呢？
答：每个公司都会有自己的maven仓库(几乎)，可以搞一些定制化的工具包，比如：日志、认证、链路、授权等。可以在工具包中加入smart-doc包进行简单开发。

可以这么做：
将smart-doc集成到工具包中，在工具包进行打包，提供给使用方，然后定制开发进行配置化管理

每个Java业务服务引入公共jar包，然后进行配置，自定义配置如下：

# 是否开启html生成，默认为false
smart-doc.html-enable=true
# html生成路径，默认为当前服务子目录doc下
smart-doc.out-path=/doc/
# 接口返回对象配置
smart-doc.response-class-name=com.sparkxmedia.xplatform.sd.api.common.result.ResultVO
# 自定义请求头
smart-doc.request-header.username=zane
smart-doc.request-header.user_id=1
smart-doc.request-header.authorization=test
# controller层包
smart-doc.package-filters=com.sparkxmedia.xplatform.sd.api.ai.controller.*,com.sparkxmedia.xplatform.sd.api.controller.*
# 如果使用swagger-ui替代smart-doc的html，则需配置获取openapi.json路径
springdoc.swagger-ui.url=/sd-api/doc/openapi.json

其核心代码如下：

package com.cuizb.tools.starter.config.doc;

import lombok.SneakyThrows;
import lombok.extern.slf4j.Slf4j;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.boot.context.properties.EnableConfigurationProperties;
import org.springframework.context.annotation.Configuration;
import org.springframework.util.ResourceUtils;
import org.springframework.web.servlet.config.annotation.CorsRegistry;
import org.springframework.web.servlet.config.annotation.ResourceHandlerRegistry;
import org.springframework.web.servlet.config.annotation.WebMvcConfigurer;

/**
 * @author: Java技术债务
 * @Date: 2021/6/6 20:03
 * Describe: 跨域解决,映射生成的静态资源
 */
@Slf4j
@Configuration
@EnableConfigurationProperties({ApiDocProperties.class})
public class WebMvcConfig implements WebMvcConfigurer {
    @Autowired
    private ApiDocProperties apiDocProperties;

    /**
     * 解决跨域问题
     * @param registry
     */
    @Override
    public void addCorsMappings(CorsRegistry registry) {
        registry.addMapping("/**")
                .allowedHeaders("*")
                .allowedMethods("*")
                .allowedOriginPatterns("/**")
                .maxAge(3600);
    }

    @SneakyThrows
    @Override
    public void addResourceHandlers(ResourceHandlerRegistry registry) {
        // 当前项目根路径
        String rootPath = ResourceUtils.getURL("").getPath();
        // 文档保存绝对路径
        rootPath = rootPath.substring(0, rootPath.length() - 1) + apiDocProperties.getOutPath();
        // 映射到当前项目根路径+用户自定义路径(当前仅支持当前项目下路径)
        String resourcesPath;
        if ("dev".equals(apiDocProperties.getProfileActive()) || "local".equals(apiDocProperties.getProfileActive())) {
            resourcesPath = "file:///" + rootPath;
        } else {
            resourcesPath = "file:///" + apiDocProperties.getOutPath();
        }

        log.info(">>>>>>>>>>>>>" + resourcesPath);
        //配置静态资源映射
        registry
                .addResourceHandler("/doc/static/**")
                .addResourceLocations(resourcesPath);
    }

}

package com.cuizb.tools.starter.config.doc;

import lombok.AllArgsConstructor;
import lombok.Data;
import lombok.NoArgsConstructor;
import org.springframework.beans.factory.annotation.Value;
import org.springframework.boot.context.properties.ConfigurationProperties;
import org.springframework.context.annotation.Configuration;

import java.util.HashMap;
import java.util.Map;

/**
 * @author Java技术债务
 * @date 2022-08-17 15:08
 * Be in awe of every code modification
 */
@Data
@AllArgsConstructor
@NoArgsConstructor
@Configuration
@ConfigurationProperties(prefix = "smart-doc")
public class ApiDocProperties {

    @Value("${server.port}")
    private int port;

    @Value("${app.id}")
    private String appId;

    @Value("${server.servlet.context-path:}")
    private String pathFilter;

    @Value("${spring.profiles.active:dev}")
    private String profileActive;

    private boolean htmlEnable;

    private String outPath;

    private String responseClassName;

    private Map<String, String> requestHeader = new HashMap<>();

    private String packageFilters;
}


/**
 * @author Java技术债务
 * @date 2022-08-16 18:17
 * Be in awe of every code modification
 */
@Slf4j
@EnableConfigurationProperties({ApiDocProperties.class})
@Controller
//@RequestMapping("${spring.application.name}/doc")
@Profile({"dev", "local", "qa", "test", "sit", "uat"})
@RequestMapping("/doc")
public class DocController {
    @Autowired
    private ApiDocProperties apiDocProperties;

    private ApiDocConfig apiDocConfig;

    public DocController() {

    }

    @GetMapping("/openapi.json")
    @ResponseBody
    public String openapi() {
        initApiDocConfig();
        ApiConfig config = apiDocConfig.getApiConfig();

        return OpenApiBuilder.buildOpenApi(config).trim().replace(" ", "");
    }
     @GetMapping("/build")
    public String buildHtml() {
        initApiDocConfig();
        ... ...
    }
}

代码解释：

  • WebMvcConfig解决跨域以及文件映射，由开发人员决定是否使用smart-doc生成的API接口文档页面，因为有的已经使用了其他产品，可以将smart-doc生成的json同步到现有的产品，当然如果你只使用smart-doc的话，不需要配置文件映射。
  • ApiDocProperties自定义配置，开发人员只关心自己当前服务的smart-doc相关配置即可
  • DocController工具包中的uri进行资源访问，可以自定义html，openapi.json等路径。也可以自定义开发，生成json文件或者json字符串等。

当前为了适用本公司，简单的自定义了一些开发，以下是简单的配置了一些路径资源：

  • 获取openapi.json地址：http://localhost:port[/server-servlet-context-path]/doc/openapi.json
  • 构建html文件地址：http://localhost:port[/server-servlet-context-path]/doc/build
  • html接口文档地址：http://localhost:port[/server-servlet-context-path]/doc/static/index.html

如果你想使用这种的话，你可以继续研究与开发。。。

总结

可以入手使用，关键是零侵入，还支持dubbo方式（虽然我未体验使用此方式）

谢谢阅读，如果有不一样的见解，请评论说出你的观点以及见解。。。觉得不错的话，介意点个赞吗？我知道你不介意，谢谢哈。。。

一些工具特性介绍等引用smart-doc官方文档：https://smart-doc-group.github.io/#/zh-cn/start/quickstart

相关文章：

  • PyTorch错误定位系列之DDP训练中 double free or corruption (out)
  • Go template详解（中）- 变量使用、if语句、迭代（数组、切片、map）、内置函数（比较、逻辑判断、打印、索引、函数调用）
  • JavaScript（三）：理解异步
  • JVM阶段（3）-OutOfMemoryError异常
  • 企业运维容器之 docker 网络
  • 【QML】 如何导入QML文档目录
  • 【前端】命令行基础，linux常用命令
  • 【ZYNQ-嵌入式】zynq学习笔记（二）—— GIPO的硬件配置和软件配置
  • vue echarts 镂空饼图配置
  • 项目二：《贪吃蛇》
  • 企业运维容器之 docker仓库
  • 快速排序sort 第k个数
  • uniapp开发微信小程序Error in onLoad hook: “SyntaxError: Unexpected end of JSON input“
  • MySQL当前链接状态查询
  • 打破平台限制，小程序如何在硬件设备上运行？
  • [Vue CLI 3] 配置解析之 css.extract
  • 【Leetcode】104. 二叉树的最大深度
  • Apache Spark Streaming 使用实例
  • classpath对获取配置文件的影响
  • docker-consul
  • exports和module.exports
  • Flannel解读
  • javascript 哈希表
  • Linux CTF 逆向入门
  • MD5加密原理解析及OC版原理实现
  • PHP 小技巧
  • Redux系列x：源码分析
  • WebSocket使用
  • 当SetTimeout遇到了字符串
  • 力扣(LeetCode)22
  • 利用jquery编写加法运算验证码
  • 浏览器缓存机制分析
  • 深度学习入门：10门免费线上课程推荐
  • 学习使用ExpressJS 4.0中的新Router
  • 源码之下无秘密 ── 做最好的 Netty 源码分析教程
  • ​ArcGIS Pro 如何批量删除字段
  • ​一、什么是射频识别?二、射频识别系统组成及工作原理三、射频识别系统分类四、RFID与物联网​
  • #{} 和 ${}区别
  • （3）选择元素——（14）接触DOM元素（Accessing DOM elements）
  • （二）PySpark3：SparkSQL编程
  • （九）c52学习之旅-定时器
  • （译）计算距离、方位和更多经纬度之间的点
  • (转)关于pipe()的详细解析
  • (转)如何上传第三方jar包至Maven私服让maven项目可以使用第三方jar包
  • ***利用Ms05002溢出找“肉鸡
  • **CI中自动类加载的用法总结
  • ... 是什么 ？... 有什么用处?
  • ./和../以及/和~之间的区别
  • .net MySql
  • .NET Standard、.NET Framework 、.NET Core三者的关系与区别？
  • .net 使用ajax控件后如何调用前端脚本
  • .net安装_还在用第三方安装.NET？Win10自带.NET3.5安装
  • .net反编译工具
  • .net开发时的诡异问题，button的onclick事件无效
  • .NET连接数据库方式