Java使用smart-doc自动生成文档

本文档介绍了一个开源工具Smart-DOC,它基于Java注释生成API文档,无需大量额外注解。相比Swagger等工具,Smart-DOC侵入性更低,解析能力强,支持多模块项目,且配置简单。尽管其界面功能和部分场景支持仍有待完善,但集成到SpringBoot项目中非常快捷,只需添加maven插件并配置即可自动生成接口文档。
摘要由CSDN通过智能技术生成

作为后端开发,写接口文档一直是一个很头痛的问题,今天推荐一个开源工具smart-doc,这个工具基于java原生的注释生成api文档,无需大量的注解配合使用。

官方地址:https://gitee.com/smart-doc-team/smart-doc

转载博客:来自51CTO博客作者上官胡闹的原创作品

一、当前市面上文档工具存在的问题
下面来列举当前市场上主流文档工具的问题:

侵入性强,需要编写大量注解,代表工具如:swagger,还有一些公司自研的文档工具
强依赖性,如果项目不想使用该工具,业务代码无法编译通过。
代码解析能力弱,使用文档不齐全,主要代表为国内众多开源的相关工具。
众多基于注释分析的工具无法解析jar包里面的注释(sources jar包),需要人工配置源码路径,无法满足DevOps构建场景。
无法支持多模块复杂项目代码分析。

二、smart-doc如何解决上述问题
通过分析源码注释自动生成API文档,不用编写任何注解,秉承注释即文档的原则,并且提供注释强制检查。
smart-doc开发了smart-doc-maven-plugin和smart-doc-gradle-plugin插件,项目仅仅依赖插件,剔除插件无修改项目不报任何编译错误。
smart-doc在国内经过上百家企业的使用,做了很多场景的分析,解析能力很强。
smart-doc的maven和gradle插件自动分析项目依赖,自动完成对自发布jar包和第三方jar包源码的加载,不需要指定任何源码路径。
smart-doc的maven和gradle能够自动识别项目依赖,多模块maven和gradle项目都不是问题。
smart-doc文档维护比较完善,码云上的wiki有20个页面介绍各种使用方式。

三、smar-doc的不足
smart-doc并非是完美的,仍然有很多不足。

界面支持不完善,没有发送请求的页面,无法满足小团队自测。
一些使用场景支持不完善,存在一些bug。
开源团队人员少,功能实现慢。

四、spring boot集成smart-doc生成文档。
上面说了关于一起其它工具的问题,也介绍了smart-doc的优缺点,下面进入正题,如何快速使用smart-doc生成文档。

4.1 添加插件

在spring boot项目pom中添加smart-doc的maven插件

 <plugin>
    <groupId>com.github.shalousun</groupId>
    <artifactId>smart-doc-maven-plugin</artifactId>
    <version>[最新版本]</version>
    <configuration>
        <!--指定生成文档使用的配置文件-->
        <configFile>./src/main/resources/smart-doc.json</configFile>
    </configuration>
    <executions>
        <execution>
            <!--不需要在编译项目时自动生成文档可注释phase-->
            <phase>compile</phase>
            <goals>
                <goal>html</goal>
            </goals>
        </execution>
    </executions>
</plugin>


4.2 添加smart-doc.json配置文件

{
  "serverUrl": "http://127.0.0.1",//服务器地址
  "isStrict": false,//是否用严格模式,严格模式强制检查注释
  "allInOne": true,//所有接口文档合并生成到一个文档
  "outPath": "src/main/resources/static/doc",//文档的输出路径
  "projectName": "smart-doc"//指定项目名称,用于显示在文档中
}

上面的几行配置中,实际上只有outPath是必须要的,其他都是非必须。相比其它工具,smart-doc配置简单又不会影响到项目。详细配置请参考smart-doc插件使用


4.3 编写controller接口

@RestController
@RequestMapping("/user")
public class UserController {

    /**
     * 添加用户
     * @param user
     * @return
     */
    @PostMapping("/add")
    public User addUser(@RequestBody User user){
        return user;
    }
}

实体类:

public class User {

    /**
     * 用户名
     */
    private String userName;

    /**
     * 昵称
     */
    private String nickName;

    /**
     * 用户地址
     */
    private String userAddress;

    /**
     * 用户年龄
     */
    private int userAge;

    /**
     * 手机号
     */
    private String phone;

    /**
     * 创建时间
     */
    private Long createTime;

    /**
     * ipv6
     */
    private String ipv6;

    /**
     * 固定电话
     */
    private String telephone;
    //省略get set
}

4.4 运行插件生成文档

 

生成文档:

当前最新的smart-doc结合插件后,已经做到了非常易于使用,只需要引入插件和根据自己需求填充相关的配置即可,非常的轻量级。

 

评论
添加红包

请填写红包祝福语或标题

红包个数最小为10个

红包金额最低5元

当前余额3.43前往充值 >
需支付:10.00
成就一亿技术人!
领取后你会自动成为博主和红包主的粉丝 规则
hope_wisdom
发出的红包
实付
使用余额支付
点击重新获取
扫码支付
钱包余额 0

抵扣说明:

1.余额是钱包充值的虚拟货币,按照1:1的比例进行支付金额的抵扣。
2.余额无法直接购买下载,可以购买VIP、付费专栏及课程。

余额充值