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

smart-doc简介

官方地址智能文档

smart-doc是一个同时支持JAVA REST API和Apache Dubbo RPC接口文档生成的工具。 smart-doc在业界率先提出推导JAVA通用定义的理念，完全根据接口源码分析生成接口文档，不使用任何Annotation侵入业务代码。你只需要按照java-doc标准编写注释，smart-doc就可以帮助你生成简单清晰的Markdown、Postman Collection2.0+、OpenAPI 3.0+文档。此外，smart-doc还支持生成美观、简洁、可调试的html5页面文档。

资讯来源开源中国

相信很多人还在使用swagger，但是swagger复杂的配置和侵入性的代码增加了开发量。 Smart-doc 基于 Java 标准注释，相对来说是非侵入性的，并且在这种便利性方面胜过 swagger。

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已生成模板，在线文档也可以通过流处理查看。 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

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

smart-doc官方文档

智能标签使用

生成了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是对源码的解析，所以每次改动源码都需要重新编译。