smart-doc Java Restful API 文档生成工具

smart-doc简介

官方地址smart-doc

smart-doc 是一款同时支持 JAVA REST API 和 Apache Dubbo RPC 接口文档生成的工具，smart-doc 在业内率先提出基于 JAVA 泛型定义推导的理念， 完全基于接口源码来分析生成接口文档，不采用任何注解侵入到业务代码中。你只需要按照 java-doc 标准编写注释， smart-doc 就能帮你生成一个简易明了的 Markdown、Postman Collection2.0+、OpenAPI 3.0 + 的文档。除此之外 smart-doc 还支持生成漂亮简洁可调试的 html5 页面文档。

资讯来源开源中国

相信很多还在用swagger，但是swagger复杂的配置和入侵式代码增大了开发量。smart-doc相对对基于java标准注解的无入侵的在这方便完胜swagger。

smart-doc使用

smart-doc快速入门

• 生成md文档

参考自smart-doc生成java 接口文档

导入依赖

<dependency>
    <groupId>com.github.shalousun</groupId>
    <artifactId>smart-doc</artifactId>
    <version>1.1</version>
    <scope>test</scope>
</dependency>

严格模式下，会检测javadoc,如过没写注释会抛出异常

接口注释

/**
 * 评论控制器
 */
@RestController
@RequestMapping("/comment")
public class CommentController {


    /**
     * 添加评论
     * @return
     * @param comment  品论
     */
    @GetMapping("/add")
    void  addComment(Comment comment){
        System.out.println("添加评论");
    }

    /**
     * 删除评论
     * @param id  编号
     * @return
     */
    @GetMapping("/delete")
    void deleteComment(Integer id){
        System.out.println("删除评论");
    }

    /**
     * 删除评论
     * @param id  编号
     * @return
     */
    @GetMapping("/update")
    void updateComment(Integer id){
        System.out.println("编辑评论");
    }

    /**
     * 查询评论
     * @return
     */
    @GetMapping("/query")
    ResponseData queryComment(){
        Comment comment = new Comment();
        comment.setName("_小许_");
        comment.setAvatar("https://www.xiaoxu.com/picture/xiaoxu.jpg");
        comment.setType(1);
        comment.setCreateTime(new Date());
        List l = new ArrayList();
        l.add(comment);
        return ResponseData.SuccessRes(l);
    }
    
}

在控制器上至少有一个注释评论控制器，在url上也是至少有一个添加评论另外两个根据实际即可，注意没有参数不要写@param不然会报错。

参数和返回值注释

/**
 * 评论表
 *
 * @author admin
 * @date 2023/03/02
 */
@Data
public class Comment {
    /** 姓名 */
    private String name;
    /**
     * 头像
     */
    private String avatar;
    /**
     * 评论
     */
    private String comment;
    /**
     * 创建时间
     */
    private Date createTime;
    /**
     * 状态
     */
    private Integer type;

}

参数和返回值注释至少有/** 姓名 */注释，不然smart-doc生产文档的字段无注释。

配置启动类生产文档

 @Test
 public void testBuilderControllersApiSimple() {
     ApiConfig config = new ApiConfig();
     //服务地址
     config.setServerUrl("http://localhost:8010");
     //生成到一个文档
     config.setAllInOne(true);
     //采用严格模式
     config.isStrict();
     //文档输出路径
     config.setOutPath("src/main/resources/static/doc");
     ApiDocBuilder.builderControllersApi(config);
     //将生成的文档输出到src/main/resources/static/doc目录下，严格模式下api-doc会检测Controller的接口注释
 }

服务器地址是生产文档的示例地址，在导入postman，apifox等工具时有用，本地参考随意设计即可；设置严格模式smart-doc会严格检查注释，文档输出路径可以是相对路径也可以是绝对路径，但一般用相对路径./(默认为根项目路径)。上面配置生成类需要再spring环境中执行，直接在单元测试类配置即可。

如下图所示生成了一个AllInOne.md的文件：

生成了md的api文档，全程只引入了一个依赖，配置了一个生成器就完成了api接口的生成而且界面简精简，是不是非常方便。

md已经生成到了templates，通过流的处理也可以在线文档观看，smart-doc也提供了maven和gradle的插件功能，用于生成文档，html和导入到postman工具。

• 生成html文档

导入依赖

<plugin>
    <groupId>com.github.shalousun</groupId>
    <artifactId>smart-doc-maven-plugin</artifactId>
    <version>1.0.3</version>
    <configuration>
        <!--指定生成文档的使用的配置文件,配置文件放在自己的项目中-->
        <configFile>./src/main/resources/smart-doc.json</configFile>
        <!--指定项目名称-->
        <projectName>API文档</projectName>
    </configuration>
    <executions>
        <execution>
            <!--如果不需要在执行编译时启动smart-doc，则将phase注释掉-->
            <phase>compile</phase>
            <goals>
                <goal>html</goal>
            </goals>
        </execution>
    </executions>
</plugin>

resources目录下新增smart-doc.json配置文件文件

{
  "serverUrl": "http://127.0.0.1:8080/api-demo/", //设置服务器地址,非必须
  "isStrict": false, //是否开启严格模式
  "allInOne": true,  //是否将文档合并到一个文件中，一般推荐为true
  "coverOld": true,  //是否覆盖旧的文件，主要用于mardown文件覆盖
  "packageFilters": "",//controller包过滤，多个包用英文逗号隔开
  "outPath": "src/main/resources/static/doc", //指定文档的输出路径
  "md5EncryptedHtmlName": false,//只有每个controller生成一个html文件是才使用
  "projectName": "CMP基础服务API文档",//配置自己的项目名称
  "showAuthor":true, //是否显示接口作者名称，默认是true,不想显示可关闭
  "dataDictionaries": [ //配置数据字典，没有需求可以不设置
    {
      "title": "状态字典",
      "enumClassName": "cn.xx.docStatusEnum",
      "codeField": "key",
      "descField": "value"
    }
  ]
}

maven运行,将会扫描controller生成文档,文档地址在上面定义的outPath参数

//生成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

tag名称	描述
@ignore	ignore tag用于过滤请求参数对象上的某个字段，设置后smart-doc不输出改字段到请求参数列表中。关于响应字段忽略的请看忽略响应字段，如果ignore加到方法上，则接口方法不会输出到文档。
@required	如果你没有使用JSR303参数验证规范实现的方式来标注字段，就可以使用@required去标注请求参数对象的字段，标注smart-doc在输出参数列表时会设置为true。
@mock	从smart-doc 1.8.0开始，mock tag用于在对象基本类型字段设置自定义文档展示值。设置值后smart-doc不再帮你生成随机值。方便可以通过smart-doc直接输出交付文档

springboot项目使用smart-doc生成api html文档

smart-doc官方文档

smart标签用法

生成了html和css，打开后如下所示：

在文档中，Required 和Since都是默认值，通过smart-doc的标签来更改：

@ignore忽略标签用于筛选请求参数对象上的某个字段。@required设置某字段为必填或非必填

smart-doc 使用说明

由于生成的是html文件所以可以随服务一同部署，如下生成html文件

配置文件释放静态资源

spring.mvc.static-path-pattern=/static/**

spring视图解析器都是从resource下开始找相关文件的，因此插件生成的css是无法自动找到的，所以需要重新配置：

编写资源控制器：

@Controller
public class DocController {
    @GetMapping("/doc")
    public String getDoc(){
        return "static/doc/index.html";
    }
}

由于smart-doc是对源码的解析，所以每次改动源码都需要重新编译。