smart-doc/README.md

134 lines
7.1 KiB
Markdown
Raw Normal View History

2019-09-17 13:54:37 +08:00
<h1 align="center"><a href="https://github.com/shalousun/smart-doc" target="_blank">Smart-Doc Project</a></h1>
2019-09-17 13:57:59 +08:00
## Introduce
2019-09-10 09:39:04 +08:00
smart-doc是一个java restful api文档生成工具smart-doc颠覆了传统类似swagger这种大量采用注解侵入来生成文档的实现方法。
2019-09-23 20:45:55 +08:00
smart-doc完全基于接口源码分析来生成接口文档完全做到零注解侵入你只需要按照java标准注释的写smart-doc就能帮你生成一个简易明了的markdown
或是一个像GitBook样式的静态html文档。如果你已经厌倦了swagger等文档工具的无数注解和强侵入污染那请拥抱smart-doc吧
2019-09-13 16:46:37 +08:00
## Features
- 零注解、零学习成本、只需要写标准java注释。
2019-09-23 20:45:55 +08:00
- 基于源代码接口定义自动推导,强大的返回结构推导。
- 支持Spring MVC,Spring Boot,Spring Boot Web Flux(controller书写方式)。
- 支持Callable,Future,CompletableFuture等异步接口返回的推导。
- 支持JavaBean上的JSR303参数校验规范。
2019-09-13 16:46:37 +08:00
- 对json请求参数的接口能够自动生成模拟json参数。
- 对一些常用字段定义能够生成有效的模拟值。
- 支持生成json返回值示例。
2019-09-30 14:47:24 +08:00
- 支持从项目外部加载源代码来生成字段注释(包括标准规范发布的jar包)。
- 支持生成多种格式文档Markdown、HTML5、Asciidoctor。
- 轻易实现在Spring Boot服务上在线查看静态HTML5 api文档。
- 开放文档数据,可自由实现接入文档管理系统。
2019-09-13 16:46:37 +08:00
## Getting started
smart-doc使用和测试可参考[smart-doc demo](https://github.com/shalousun/api-doc-test)。
```
# git clone https://github.com/shalousun/api-doc-test.git
```
2019-09-23 22:06:33 +08:00
你可以启动这个Spring Boot的项目然后访问`http://localhost:8080/doc/api.html`来浏览smart-doc生成的接口文档。
2019-09-13 16:46:37 +08:00
### Maven dependency
2019-09-10 09:39:04 +08:00
```
<dependency>
<groupId>com.github.shalousun</groupId>
<artifactId>smart-doc</artifactId>
2019-09-30 14:47:24 +08:00
<version>1.7.0</version>
2019-09-10 09:39:04 +08:00
<scope>test</scope>
</dependency>
```
2019-09-13 16:46:37 +08:00
### Create a unit test
2019-09-23 21:57:46 +08:00
通过运行一个单元测试来让Smart-doc为你生成一个简洁明了的api文档
2019-09-10 09:39:04 +08:00
```
/**
2019-09-30 14:47:24 +08:00
* Description:
* ApiDoc测试
2019-09-10 09:39:04 +08:00
*
* @author yu 2018/06/11.
*/
public class ApiDocTest {
/**
2019-09-30 14:47:24 +08:00
* 包括设置请求头,缺失注释的字段批量在文档生成期使用定义好的注释
2019-09-10 09:39:04 +08:00
*/
@Test
public void testBuilderControllersApi() {
ApiConfig config = new ApiConfig();
2019-09-30 14:47:24 +08:00
config.setServerUrl("http://localhost:8080");
//true会严格要求注释推荐设置true
2019-09-10 09:39:04 +08:00
config.setStrict(true);
2019-09-30 14:47:24 +08:00
//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")
);
//设置请求头,如果没有请求头,可以不用设置
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后期遇到同名字段则直接给相应字段加注释
2019-09-10 09:39:04 +08:00
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("响应代码")
);
2019-09-30 14:47:24 +08:00
//设置项目错误码列表,设置自动生成错误列表,
2019-09-10 09:39:04 +08:00
List<ApiErrorCode> errorCodeList = new ArrayList<>();
2019-09-30 14:47:24 +08:00
for (ErrorCodeEnum codeEnum : ErrorCodeEnum.values()) {
2019-09-10 09:39:04 +08:00
ApiErrorCode errorCode = new ApiErrorCode();
2019-09-30 14:47:24 +08:00
errorCode.setValue(codeEnum.getCode()).setDesc(codeEnum.getDesc());
2019-09-10 09:39:04 +08:00
errorCodeList.add(errorCode);
}
2019-09-30 14:47:24 +08:00
//如果没需要可以不设置
2019-09-10 09:39:04 +08:00
config.setErrorCodes(errorCodeList);
2019-09-30 14:47:24 +08:00
//非必须只有当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")
);
long start = System.currentTimeMillis();
2019-09-10 09:39:04 +08:00
ApiDocBuilder.builderControllersApi(config);
2019-09-30 14:47:24 +08:00
//@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);
long end = System.currentTimeMillis();
DateTimeUtil.printRunTime(end, start);
}
2019-09-10 09:39:04 +08:00
}
```
2019-09-13 16:46:37 +08:00
### Generated document example
#### 接口头部效果图
2019-09-10 09:39:04 +08:00
![输入图片说明](https://images.gitee.com/uploads/images/2018/0905/173104_abcf4345_144669.png "1.png")
2019-09-13 16:46:37 +08:00
#### 请求参数示例效果图
2019-09-10 09:39:04 +08:00
![请求参数示例](https://images.gitee.com/uploads/images/2018/0905/172510_853735b9_144669.png "2.png")
2019-09-13 16:46:37 +08:00
#### 响应参数示例效果图
2019-09-10 09:39:04 +08:00
![响应参数示例](https://images.gitee.com/uploads/images/2018/0905/172538_1918820c_144669.png "3.png")
2019-09-13 16:57:31 +08:00
## Releases
2019-09-13 16:46:37 +08:00
[发布记录](https://github.com/shalousun/smart-doc/blob/master/RELEASE.md/)
## Other reference
- [smart-doc功能使用介绍](https://my.oschina.net/u/1760791/blog/2250962)
## License
2019-09-23 21:57:46 +08:00
Smart-doc is under the Apache 2.0 license. See the [LICENSE](https://github.com/shalousun/smart-doc/blob/master/license.txt) file for details.
2019-09-13 16:46:37 +08:00
## Contact
2019-09-23 21:57:46 +08:00
Email 836575280@qq.com