smart-doc/README_CN.md

20 KiB
Raw Blame History

Smart-Doc Project

maven License closed pull requests java version

Introduce

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

\color{red}{你给我的star胜过所有读过的诗—smart-doc}

无论你是很有经验的大佬、还是刚入行的萌新。遇到使用疑惑时我们希望你能仔细阅读smart-doc官方码云的wiki文档。我们将smart-doc及其插件的 每一个配置项和可能在日常中遇到的问题都整理到了文档中。仔细阅读文档就是对开源项目最大的支持。 wiki文档

Features

  • 零注解、零学习成本、只需要写标准JAVA注释。
  • 基于源代码接口定义自动推导,强大的返回结构推导。
  • 支持Spring MVC、Spring Boot、Spring Boot Web Flux(controller书写方式)、Feign。
  • 支持Callable、Future、CompletableFuture等异步接口返回的推导。
  • 支持JavaBean上的JSR303参数校验规范包括分组验证。
  • 对JSON请求参数的接口能够自动生成模拟JSON参数。
  • 对一些常用字段定义能够生成有效的模拟值。
  • 支持生成JSON返回值示例。
  • 支持从项目外部加载源代码来生成字段注释(包括标准规范发布的jar包)。
  • 支持生成多种格式文档Markdown、HTML5、Asciidoctor、Postman Collection、OpenAPI 3.0。 Up- 开放文档数据,可自由实现接入文档管理系统。
  • 支持导出错误码和定义在代码中的各种字典码到接口文档。
  • 支持Maven、Gradle插件式轻松集成。
  • 支持Apache Dubbo RPC接口文档生成。
  • debug接口调试html5页面完全支持文件上传下载(@download tag标记下载方法)测试。

Best Practice

smart-doc + Torna 组成行业领先的文档生成和管理解决方案使用smart-doc无侵入完成Java源代码分析和提取注释生成API文档自动将文档推送到Torna企业级接口文档管理平台。

smart-doc+torna

smart-doc+Torna文档自动化

Torna是由smart-doc官方独家推动联合研发的企业级文档管理系统因此smart-doc官方不会对接其它任何的外部文档管理系统例如像showdoc、yapi 之类的对接请自定内部处理也不要再给我们提其他文档系统对接的PR。我们核心是把smart-doc+Torna的这套方案打造好。

Getting Started

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

# git clone https://gitee.com/smart-doc-team/smart-doc-example-cn.git

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

maven多模块项目请参考

# git clone https://gitee.com/smart-doc-team/spring-boot-maven-multiple-module.git

Add Maven Plugin

smart-doc官方目前已经开发完成Maven插件Gradle插件 你可以根据自己的构建工具来选择使用Maven插件或者是Gradle插件。

Add Plugin

<plugin>
    <groupId>com.github.shalousun</groupId>
    <artifactId>smart-doc-maven-plugin</artifactId>
    <version>[最新版本]</version>
    <configuration>
        <!--指定生成文档的使用的配置文件,配置文件放在自己的项目中-->
        <configFile>./src/main/resources/smart-doc.json</configFile>
        <!--指定项目名称-->
        <projectName>测试</projectName>
        <!--smart-doc实现自动分析依赖树加载第三方依赖的源码如果一些框架依赖库加载不到导致报错这时请使用excludes排除掉-->
        <excludes>
            <!--格式为groupId:artifactId;参考如下-->
            <exclude>com.alibaba:fastjson</exclude>
        </excludes>
        <!--自1.0.8版本开始插件提供includes支持,配置了includes后插件会按照用户配置加载而不是自动加载因此使用时需要注意-->
        <!--smart-doc能自动分析依赖树加载所有依赖源码原则上会影响文档构建效率因此你可以使用includes来让插件加载你配置的组件-->
        <includes>
            <!--格式为groupId:artifactId;参考如下-->
            <!--也可以支持正则式如com.alibaba:.* -->
            <include>com.alibaba:fastjson</include>
        </includes>
    </configuration>
    <executions>
        <execution>
            <!--如果不需要在执行编译时启动smart-doc则将phase注释掉-->
            <phase>compile</phase>
            <goals>
                <!--smart-doc提供了html、openapi、markdown等goal可按需配置-->
                <goal>html</goal>
            </goals>
        </execution>
    </executions>
</plugin>

Configuration

在项目中添加创建一个smart-doc.json配置文件,插件读取这个配置来生成项目的文档, 这个配置内容实际上就是以前采用单元测试编写的ApiConfig转成json后的结果因此关于配置项说明可以参考原来单元测试的配置。

最小配置单元:

{
   "outPath": "D://md2" //指定文档的输出路径,相对路径时请用./开头eg:./src/main/resources/static/doc
}

如果你想把html文档也打包到应用中一起访问则建议你配置路径为src/main/resources/static/doc

仅仅需要上面一行配置就能启动smart-doc-maven-plugin插件根据自己项目情况更多详细的配置参考下面。 详细配置说明

{
  "serverUrl": "http://127.0.0.1", //服务器地址,非必须。导出postman建议设置成http://{{server}}方便直接在postman直接设置环境变量
  "pathPrefix": "", //设置path前缀,非必须。如配置Servlet ContextPath 。@since 2.2.3
  "isStrict": false, //是否开启严格模式
  "allInOne": true,  //是否将文档合并到一个文件中一般推荐为true
  "outPath": "D://md2", //指定文档的输出路径
  "coverOld": true,  //是否覆盖旧的文件主要用于mardown文件覆盖
  "createDebugPage": true,//@since 2.0.0 smart-doc支持创建可以测试的html页面仅在AllInOne模式中起作用。
  "packageFilters": "",//controller包过滤多个包用英文逗号隔开2.2.2开始需要采用正则com.test.controller.*
  "md5EncryptedHtmlName": false,//只有每个controller生成一个html文件是才使用
  "style":"xt256", //基于highlight.js的代码高设置,可选值很多可查看码云wiki喜欢配色统一简洁的同学可以不设置
  "projectName": "smart-doc",//配置自己的项目名称
  "skipTransientField": true,//目前未实现
  "sortByTitle":false,//接口标题排序默认为false,@since 1.8.7版本开始
  "showAuthor":true,//是否显示接口作者名称默认是true,不想显示可关闭
  "requestFieldToUnderline":true,//自动将驼峰入参字段在文档中转为下划线格式,//@since 1.8.7版本开始
  "responseFieldToUnderline":true,//自动将驼峰入参字段在文档中转为下划线格式,//@since 1.8.7版本开始
  "inlineEnum":true,//设置为true会将枚举详情展示到参数表中默认关闭//@since 1.8.8版本开始
  "recursionLimit":7,//设置允许递归执行的次数用于避免一些对象解析卡主默认是7正常为3次以内//@since 1.8.8版本开始
  "allInOneDocFileName":"index.html",//自定义设置输出文档名称, @since 1.9.0
  "requestExample":"true",//是否将请求示例展示在文档中默认true@since 1.9.0
  "responseExample":"true",//是否将响应示例展示在文档中默认为true@since 1.9.0
  "requestParamsTable": true, //是否将请求参数表展示在文档中默认true@since 2.2.5
  "responseParamsTable": true //是否将响应参数表展示在文档中, 默认true@since 2.2.5
  "urlSuffix":".do",//支持SpringMVC旧项目的url后缀,@since 2.1.0
  "displayActualType":false,//配置true会在注释栏自动显示泛型的真实类型短类名@since 1.9.6
  "appKey": "20201216788835306945118208",// torna平台对接appKey,, @since 2.0.9
  "appToken": "c16931fa6590483fb7a4e85340fcbfef", //torna平台appToken,@since 2.0.9
  "secret": "W.ZyGMOB9Q0UqujVxnfi@.I#V&tUUYZR",//torna平台secret@since 2.0.9
  "openUrl": "http://localhost:7700/api",//torna平台地址填写自己的私有化部署地址@since 2.0.9
  "debugEnvName":"测试环境", //torna环境名称
  "debugEnvUrl":"http://127.0.0.1",//推送torna配置接口服务地址
  "tornaDebug":false,//启用会推送日志
  "replace":true, // 推送文档到torna强制替换 @since 2.2.4
  "ignoreRequestParams":[ //忽略请求参数对象,把不想生成文档的参数对象屏蔽掉,@since 1.9.2
     "org.springframework.ui.ModelMap"
   ],
  "dataDictionaries": [{ //配置数据字典,没有需求可以不设置
      "title": "http状态码字典", //数据字典的名称
      "enumClassName": "com.power.common.enums.HttpCodeEnum", //数据字典枚举类名称
      "codeField": "code",//数据字典字典码对应的字段名称
      "descField": "message"//数据字典对象的描述信息字典
  }],
  "errorCodeDictionaries": [{ //错误码列表,没有需求可以不设置
    "title": "title",
    "enumClassName": "com.power.common.enums.HttpCodeEnum", //错误码枚举类
    "codeField": "code",//错误码的code码字段名称
    "descField": "message"//错误码的描述信息对应的字段名
  }],
  "revisionLogs": [{ //文档变更记录,非必须
      "version": "1.0", //文档版本号
      "revisionTime": "2020-12-31 10:30", //文档修订时间
      "status": "update", //变更操作状态,一般为:创建、更新等
      "author": "author", //文档变更作者
      "remarks": "desc" //变更描述
    }
  ],
  "customResponseFields": [{ //自定义添加字段和注释一般用户处理第三方jar包库非必须
      "name": "code",//覆盖响应码字段
      "desc": "响应代码",//覆盖响应码的字段注释
      "ownerClassName": "org.springframework.data.domain.Pageable", //指定你要添加注释的类名
      "ignore":true, //设置true会被自动忽略掉不会出现在文档中
      "value": "00000"//设置响应码的值
  }],
  "customRequestFields": [{ //自定义请求体的注释,@since 2.1.3,非必须
       "name":"code", //属性名
       "desc":"状态码", //描述
       "ownerClassName":"com.xxx.constant.entity.Result", //属性对应的类全路径
       "value":"200", //默认值或者mock值
       "required":true, //是否必填
       "ignore":false //是否忽略
  }],
  "requestHeaders": [{ //设置请求头,没有需求可以不设置
      "name": "token",//请求头名称
      "type": "string",//请求头类型
      "desc": "desc",//请求头描述信息
      "value":"token请求头的值",//不设置默认null
      "required": false,//是否必须
      "since": "-",//什么版本添加的改请求头
      "pathPatterns": "/app/test/**",//请看https://gitee.com/smart-doc-team/smart-doc/wikis/请求头高级配置?sort_id=4178978
      "excludePathPatterns":"/app/page/**"//请看https://gitee.com/smart-doc-team/smart-doc/wikis/请求头高级配置?sort_id=4178978
  },{
      "name": "appkey",//请求头
      "type": "string",//请求头类型
      "desc": "desc",//请求头描述信息
      "value":"appkey请求头的值",//不设置默认null
      "required": false,//是否必须
      "pathPatterns": "/test/add,/testConstants/1.0",//正则表达式过滤请求头,url匹配上才会添加该请求头多个正则用分号隔开
      "since": "-"//什么版本添加的改请求头
  }],
  "requestParams": [ //公共请求参数(通过拦截器处理的场景)@since 2.2.3,没有需求请不要设置
    {
      "name": "configPathParam",//请求头名称
      "type": "string",//请求头类型
      "desc": "desc",//请求头描述信息
      "paramIn": "path",
      "value":"testPath",//不设置默认null
      "required": false,//是否必须
      "since": "-",//什么版本添加的改请求头
      "pathPatterns": "*",//正则表达式过滤请求头
      "excludePathPatterns":"/app/page/**" //参考请求头中的用法
    },
    {
      "name": "configQueryParam",//请求头名称
      "type": "string",//请求头类型
      "desc": "desc",//请求头描述信息
      "paramIn": "query",
      "value":"testQuery",//不设置默认null
      "required": false,//是否必须
      "since": "-",//什么版本添加的改请求头
      "pathPatterns": "*",//正则表达式过滤请求头
      "excludePathPatterns":"/app/page/**"
    }
  ],
  "rpcApiDependencies":[{ // 项目开放的dubbo api接口模块依赖配置后输出到文档方便使用者集成
        "artifactId":"SpringBoot2-Dubbo-Api",
        "groupId":"com.demo",
        "version":"1.0.0"
   }],
  "rpcConsumerConfig": "src/main/resources/consumer-example.conf",//文档中添加dubbo consumer集成配置用于方便集成方可以快速集成
  "apiObjectReplacements": [{ // 自smart-doc 1.8.5开始你可以使用自定义类覆盖其他类做文档渲染,非必须
      "className": "org.springframework.data.domain.Pageable",
      "replacementClassName": "com.power.doc.model.PageRequestDto" //自定义的PageRequestDto替换Pageable做文档渲染
  }],
  "apiConstants": [{//从1.8.9开始配置自己的常量类smart-doc在解析到常量时自动替换为具体的值非必须
        "constantsClassName": "com.power.doc.constants.RequestParamConstant" //引用常量时需要用RequestParamConstant.xxx才能被正确解析
  }],
  "responseBodyAdvice":{ //自smart-doc 1.9.8起非必须项ResponseBodyAdvice统一返回设置(不要随便配置根据项目的技术来配置)可用ignoreResponseBodyAdvice tag来忽略
  		"className":"com.power.common.model.CommonResult" //通用响应体
  },
  "requestBodyAdvice":{ ////自smart-doc 2.1.4 起支持设置RequestBodyAdvice统一请求包装类非必须
         "className":"com.power.common.model.CommonResult"
  },
  "groups": [ // @since 2.2.5, 对不同的controller进行分组
    {
      "name": "测试分组",
      "apis": "com.power.doc.controller.app.*"
    }
  ]
}

上面的JSON配置实例中只有"outPath"是必填项。其他额外配置项请根据实际情况来配置,请不要胡乱复制上面的全配置到自己的项目中 可能引起使用错误。

注意: 对于老用户完全可以通过Fastjson或者是Gson库将ApiConfig转化成JSON配置。

Use Maven Command

添加好插件和配置文件后可以直接运行Maven命令生成文档。

//生成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
// 生成 Open Api 3.0+,Since smart-doc-maven-plugin 1.1.5
mvn -Dfile.encoding=UTF-8 smart-doc:openapi
// 生成文档推送到Torna平台
mvn -Dfile.encoding=UTF-8 smart-doc:torna-rest

// Apache Dubbo RPC文档
// Generate html
mvn -Dfile.encoding=UTF-8 smart-doc:rpc-html
// Generate markdown
mvn -Dfile.encoding=UTF-8 smart-doc:rpc-markdown
// Generate adoc
mvn -Dfile.encoding=UTF-8 smart-doc:rpc-adoc

// 生成dubbo接口文档推送到torna
mvn -Dfile.encoding=UTF-8 smart-doc:torna-rpc

注意: 尤其在window系统下如果实际使用Maven命令行执行文档生成可能会出现乱码因此需要在执行时指定-Dfile.encoding=UTF-8

Use in IDEA

idea中smart-doc-maven插件使用

Use gradle plugin

如果你使用Gradle来构建项目你可以参考Gradle插件的使用文档来集成 smart-doc-gradle-plugin

Use Junit Test

从smart-doc 1.7.9开始官方提供了Maven插件使用smart-doc的Maven插件后不再需要创建单元测试。 单元测试生成文档

单元测试集成存在很多局限性:
1. 对于多模块项目源码注释很麻烦,也不符合正常开发团队的开发协作。
2. 不方便与CI工具集成

Generated document example

点击查看文档生成文档效果图

Building

如果你需要自己构建smart-doc那可以使用下面命令构建需要依赖Java 1.8。

mvn clean install -Dmaven.test.skip=true

TODO

  • Jakarta RS-API 2.x

Other reference

License

smart-doc is under the Apache 2.0 license. See the LICENSE file for details.

注意: smart-doc源代码文件全部带有版权注释使用关键代码二次开源请保留原始版权否则后果自负

Who is using

排名不分先后,更多接入公司,欢迎在https://gitee.com/smart-doc-team/smart-doc/issues/I1594T登记(仅供开源用户参考)

IFLYTEK                           

Award situation

  • 2020 年度 OSC 中国开源项目评选”活动中获得「最积极运营项目」

Acknowledgements

感谢JetBrains SoftWare 为本开源项目提供的免费Open Source license。

Contact

愿意参与构建smart-doc或者是需要交流问题可以加入qq群

Donate

如果您觉得我们的开源软件对你有所帮助,请扫下方二维码打赏我们一杯咖啡