持续创作，加速成长！这是我参与「掘金日新计划 · 6 月更文挑战」的第9天，点击查看活动详情

背景

记得刚开始工作的时候，都是用手写md接口文档，当时真是苦不堪言。后来接触到swagger，终于不用手写接口文档了，但是集成swagger也是个不小的工作量。

总结下个人对于swagger的缺点吧

有比较大的学习成本，需要掌握他的注解及api
代码侵入性很强，只要你需要文档输出的地方，都会有你代码侵入的地方

所以其实我并不喜欢用swagger。

后来偶然间看到smart-doc,发现用完真的就一去不复返了

smart-doc

smart-doc 完全基于接口源码分析来生成接口文档，完全做到零注解侵入。只要你按照标准的Java注释编写，smart-doc就能给你生成一个接口文档，目前支持Markdown、doc、HTML等文件格式

springboot集成smart-doc

说了这么多，我们来讲它集成到springboot项目中，看看实际效果如何吧

集成步骤

添加配置文件
引入插件没错就是这么简单

添加配置文件

smart-doc提供的配置有很多，我认为比较常用的就是下面几个属性吧

{
  "serverUrl": "http://127.0.0.1:8082/",// 服务地址
  "allInOne": true,//是否将文档合并到一个文件中，一般推荐为true
  "coverOld": true,//是否覆盖旧的文件
  "createDebugPage": true,//创建一个类似swagger的可调试接口的文档页面
  "packageFilters": "com.cnsesan.shennong.approval.controller.*",//controller包过滤，多个包用英文逗号隔开
  "projectName": "shengnong-approval",//项目名称
  "allInOneDocFileName":"index.html",//自定义设置输出文档名称
  "showAuthor":true,//是否展示作者
  "outPath": "src/main/resources/static/doc",//接口文档输出位置
  // 文档变更记录
  "revisionLogs": [{
    "version": "1.0",
    "revisionTime": "2020-12-31 10:30",
    "status": "update",
    "author": "mumuwen",
    "remarks": "desc"
  }]
}

引入插件

<plugin>
    <groupId>com.github.shalousun</groupId>
    <artifactId>smart-doc-maven-plugin</artifactId>
    <version>2.4.7</version>
    <configuration>
        <!--指定生成文档的使用的配置文件,配置文件放在自己的项目中-->
        <configFile>./src/main/resources/smart-doc.json</configFile>
        <!--指定项目名称-->
        <projectName>smart-doc-test</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>
</plugin>

使用

然后我们就能在项目中看到smart-doc插件了

我们可以根据自己的喜好选择要输出的接口文档就可以了

当然smart-doc还有很多高级的功能，比如在线调试接口，集成torna进行接口管理，可以参考官网按需选择

参考文献、资料

smart-doc官网：smart-doc-group.github.io/#/zh-cn/sta…

还在愁着接口文档吗？赶紧看过来

背景