是什么让中国上百家公司放弃swagger?

在过去的java web开发中，swagger一直占据着接口文档生成的大半壁江山。尽管swagger有着复杂的配置和极强的代码侵入性，但是开发者找不到好的工具来替代。国外出名的其他项目主要是apidoc，但是apidoc使用更加复杂始终无法撼动swagger。国内的很多开发者一直蠢蠢欲动，试图想开发一些低侵入的文档生成工具，从2018年到现在，国内码云平台上提交了好几个java生成restful api接口文档的项目。但是很多项目几乎无法被外部公司所使用，缺乏大量的使用测试。

2017年底一个决绝使用swagger的开发者经过冥思苦相和翻墙各种查阅资料，终于想到了基于源码和注释分析生成文档的思路，并且开始着手开发，这个工具就是smart-doc。2018年8月smart-doc正式开源并被一加首次引入到公司。2019年smart-doc经过不断迭代和与用户的沟通，smart-doc已经进入了国内上百家公司，因为smart-doc的零侵入和零注解特性，使得他们抛弃了swagger后选择了smart-doc。

smart-doc简介

smart-doc是一个java restful api文档生成工具，smart-doc颠覆了传统类似swagger这种大量采用注解侵入来生成文档的实现方法。 smart-doc完全基于接口源码分析来生成接口文档，完全做到零注解侵入，你只需要按照java标准注释的写，smart-doc就能帮你生成一个简易明了的markdown 或是一个像GitBook样式的静态html文档。如果你已经厌倦了swagger等文档工具的无数注解和强侵入污染，那请拥抱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 json。
• 轻易实现在Spring Boot服务上在线查看静态HTML5 api文档。
• 开放文档数据，可自由实现接入文档管理系统。
• 支持导出错误码和定义在代码中的各种字典码到接口文档。

集成到SpringBoot项目

smart-doc使用和测试可参考 smart-doc demo 。

# git clone https://gitee.com/sunyurepository/api-doc-test.git
复制代码

你可以启动这个Spring Boot的项目，然后访问 http://localhost:8080/doc/api.html 来浏览smart-doc生成的接口文档。

Dependency

maven

<dependency>
    <groupId>com.github.shalousun</groupId>
    <artifactId>smart-doc</artifactId>
    <version>{最新版本}</version>
    <scope>test</scope>
</dependency>
复制代码

gradle

testCompile 'com.github.shalousun:smart-doc:最新版本'
复制代码

Create a unit test

通过运行一个单元测试来让Smart-doc为你生成一个简洁明了的api文档

/**
 * Description:
 * ApiDoc测试
 *
 * @author yu 2018/06/11.
 */
public class ApiDocTest {

    /**
     * 包括设置请求头，缺失注释的字段批量在文档生成期使用定义好的注释
     */
    @Test
    public void testBuilderControllersApi() {
        ApiConfig config = new ApiConfig();
        config.setServerUrl("http://localhost:8080");
        //true会严格要求注释，推荐设置true
        config.setStrict(true);
        //true会将文档合并导出到一个markdown
        config.setAllInOne(false);
        //生成html时加密文档名不暴露controller的名称
        config.setMd5EncryptedHtmlName(true);

        //指定文档输出路径
        //@since 1.7 版本开始，选择生成静态html doc文档可使用该路径：DocGlobalConstants.HTML_DOC_OUT_PATH;
        config.setOutPath(DocGlobalConstants.HTML_DOC_OUT_PATH);
        // @since 1.2,如果不配置该选项，则默认匹配全部的controller,
        // 如果需要配置有多个controller可以使用逗号隔开
        config.setPackageFilters("com.power.doc.controller");
        //不指定SourcePaths默认加载代码为项目src/main/java下的,如果项目的某一些实体来自外部代码可以一起加载
        config.setSourceCodePaths(
                //自1.7.0版本开始，在此处可以不设置本地代码路径，单独添加外部代码路径即可
//            SourceCodePath.path().setDesc("本项目代码").setPath("src/main/java"),
            SourceCodePath.path().setDesc("加载项目外代码").setPath("E://ApplicationPower//ApplicationPower//Common-util//src//main//java")
        );
        //since 1.7.5
        //如果该选项的值为false,则smart-doc生成allInOne.md文件的名称会自动添加版本号
        config.setCoverOld(true);
        //since 1.7.5
        //设置项目名(非必须)，如果不设置会导致在使用一些自动添加标题序号的工具显示的序号不正常
        config.setProjectName("抢购系统");
        //设置请求头，如果没有请求头，可以不用设置
        config.setRequestHeaders(
                ApiReqHeader.header().setName("access_token").setType("string").setDesc("Basic auth credentials"),
                ApiReqHeader.header().setName("user_uuid").setType("string").setDesc("User Uuid key")
        );
        //对于外部jar的类，编译后注释会被擦除，无法获取注释，但是如果量比较多请使用setSourcePaths来加载外部代码
        //如果有这种场景，则自己添加字段和注释，api-doc后期遇到同名字段则直接给相应字段加注释
        config.setCustomResponseFields(
                CustomRespField.field().setName("success").setDesc("成功返回true,失败返回false"),
                CustomRespField.field().setName("message").setDesc("接口响应信息"),
                CustomRespField.field().setName("data").setDesc("接口响应数据"),
                CustomRespField.field().setName("code").setValue("00000").setDesc("响应代码")
        );

        //设置项目错误码列表，设置自动生成错误列表,
        List<ApiErrorCode> errorCodeList = new ArrayList<>();
        for (ErrorCodeEnum codeEnum : ErrorCodeEnum.values()) {
            ApiErrorCode errorCode = new ApiErrorCode();
            errorCode.setValue(codeEnum.getCode()).setDesc(codeEnum.getDesc());
            errorCodeList.add(errorCode);
        }
        //如果没需要可以不设置
        config.setErrorCodes(errorCodeList);

        //非必须只有当setAllInOne设置为true时文档变更记录才生效，https://gitee.com/sunyurepository/ApplicationPower/issues/IPS4O
        config.setRevisionLogs(
                RevisionLog.getLog().setRevisionTime("2018/12/15").setAuthor("chen").setRemarks("测试").setStatus("创建").setVersion("V1.0"),
                RevisionLog.getLog().setRevisionTime("2018/12/16").setAuthor("chen2").setRemarks("测试2").setStatus("修改").setVersion("V2.0")
        );
        
        //since 1.7.5
        //文档添加数据字典
        config.setDataDictionaries(
            ApiDataDictionary.dict().setTitle("订单状态").setEnumClass(OrderEnum.class).setCodeField("code").setDescField("desc"),
            ApiDataDictionary.dict().setTitle("订单状态1").setEnumClass(OrderEnum.class).setCodeField("code").setDescField("desc")
        );


        long start = System.currentTimeMillis();
        ApiDocBuilder.builderControllersApi(config);

        //@since 1.7+版本开始，smart-doc支持生成带书签的html文档，html文档可选择下面额方式
        //HtmlApiDocBuilder.builderControllersApi(config);
        //@since 1.7+版本开始，smart-doc支撑生成AsciiDoc文档，你可以把AsciiDoc转成HTML5的格式。
        //@see https://gitee.com/sunyurepository/api-doc-test
        //AdocDocBuilder.builderControllersApi(config);
        //@since 1.7.8,smart-doc支持导出Postman测试的json
        //PostmanJsonBuilder.BuildPostmanApi(config);
                
        long end = System.currentTimeMillis();
        DateTimeUtil.printRunTime(end, start);
    }
}
复制代码

接口文档生成样例

实体代码：

public class SimpleUser {

    /**
     * 用户名
     * @since v1.0
     */
    @NotNull
    private String username;

    /**
     * 密码
     * @since v1.0
     */
    private String password;

    /**
     * 昵称
     * @since v1.0
     */
    private String nickName;

    /**
     * 电话
     * @since v1.0
     */
    private String mobile;

}
复制代码

Controller层接口

/**
 * smart-doc接口生成测试
 * @author cht 2019/10/16.
 */
@RestController
public class ApiNoteController {

    /**
     * 接口生成测试
     * @return
     */
    @PostMapping(value = "/test")
    public CommonResult<SimpleUser> test(@RequestBody SimpleUser user){
        return CommonResult.ok().setResult(user);
    }
}

复制代码

文档效果如下：

smart-doc接口生成测试

接口生成测试

URL: http://localhost:8080/test

Type:POST

Content-Type:application/json; charset=utf-8

Description:接口生成测试

Request-headers:

Request-parameters:

Request-example:

{
	"username":"智宸.罗",
	"password":"xzl6bk",
	"nickName":"sofia.crist",
	"mobile":"17545455139"
}
复制代码

Response-fields:

Response-example:

{
	"success":true,
	"message":"success",
	"data":{
		"username":"智宸.罗",
		"password":"o85ttk",
		"nickName":"sofia.crist",
		"mobile":"17545455139"
	},
	"code":"86061",
	"timestamp":"2019-12-05 23:50:08"
}
复制代码

以上可以看出，使用smart-doc你只需要写好标准的javadoc注释。smart-doc并不会污染你的业务代码。

smart-doc相关使用文档

• smart-doc wiki

smart-doc项目地址

• github
• gitee

总结

通过上面的介绍包括样例展示，很容易反应smart-doc为什么被上百家中国公司使用。smart-doc完全无侵入，并且能够生成赶紧整洁的html静态文档、markdown格式的文档(上面的文档样例数据就来自smart-doc生成markdown)、adoc文档，甚至能够生成一键导入到postman测试的接口json文件。过去一年多的时间里，smart-doc经过很多用户是使用验证，已经趋于稳定和成熟，后续将陪伴用户一起变得更好。也希望smart-doc能够去帮助到更多的用户和吸纳更多的代码贡献者。

smart-doc用户评价

• 最强大的doc组件，强制要求了规范，也不会污染代码，欣喜之情溢于言表!
• smartdoc从注释入手，即规范强化了文档的编写又能提供源码文档之外的api功能，真的对得起smart的称谓。
• smart-doc用起来非常舒服，希望越来越好。