SpringBoot 集成 Smart-Doc

一 什么是 Smart-Doc

       smart-doc 是一个 java restful api 文档生成工具，smart-doc 颠覆了传统类似 swagger 这种大量采用注解侵入来生成文档的实现方法。 smart-doc 完全基于接口源码分析来生成接口文档，完全做到零注解侵入，你只需要按照 java 标准注释的写，smart-doc就能帮你生成一个简易明了的 markdown 或是一个像 GitBook 样式的静态 html 文档。如果你已经厌倦了 swagger 等文档工具的无数注解和强侵入污染，那请拥抱 smart-doc 吧！

二  Smart-Doc 功能特性

• 零注解、零学习成本、只需要写标准java注释。
• 基于源代码接口定义自动推导，强大的返回结构推导。
• 支持Spring MVC,Spring Boot,Spring Boot Web Flux(controller书写方式)。
• 支持Callable,Future,CompletableFuture等异步接口返回的推导。
• 支持JavaBean上的JSR303参数校验规范。
• 对json请求参数的接口能够自动生成模拟json参数。
• 对一些常用字段定义能够生成有效的模拟值。
• 支持生成json返回值示例。
• 支持从项目外部加载源代码来生成字段注释(包括标准规范发布的jar包)。
• 支持生成多种格式文档：Markdown、HTML5、Asciidoctor、Postman Collection。
• 轻易实现在Spring Boot服务上在线查看静态HTML5 api文档。
• 开放文档数据，可自由实现接入文档管理系统。
• 支持生成dubbo rpc文档。

三 集成 Smart-Doc

3.1 引入依赖

    com.github.shalousun
    smart-doc
    1.8.1
    test

3.2 创建 User 类

public class User {
    /**
     * 姓名
     */
    private String name;

    /**
     * 年龄
     */
    private String age;

    /**
     * 电话
     */
    private String mobile;
}

3.3 创建 UserController 类

/**
 * 用户管理
 */
@RestController
@RequestMapping("/user")
public class UserController {
    
    /**
     * 添加用户
     * @param user
     * @return
     */
    @PostMapping("/addUser")
    public User getUser(@RequestBody User user) {
        return new User();
    }
}

3.4 新建一个单元测试类生成 html5 文档

import com.power.common.enums.HttpCodeEnum;
import com.power.doc.builder.HtmlApiDocBuilder;
import com.power.doc.constants.DocGlobalConstants;
import com.power.doc.model.*;
import org.junit.jupiter.api.Test;
import org.springframework.boot.test.context.SpringBootTest;

import java.util.ArrayList;
import java.util.List;

@SpringBootTest
public class ApiDocTests {
    
    @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
        config.setOutPath(DocGlobalConstants.HTML_DOC_OUT_PATH);

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

        //设置错误错列表，遍历自己的错误码设置给Smart-doc即可
        List 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);
    }
}

执行单元测试生成 html5 文档。

3.5 查看文档

启动 springboot 服务，访问 http://localhost:8080/doc/index.html 得到如下结果。

4 参考文档

 https://gitee.com/sunyurepository/smart-doc/wikis/%E6%96%87%E6%A1%A3%E7%94%9F%E6%88%90?sort_id=1653105