解析源码文件,通过源码及其中的注释生成文档信息。目前为止注释中使用的Tag都是Java注释的标准Tag,后续可能会添加一些必要的自定义Tag,甚至有可能提供Tag扩展机制 —— 由使用者自定义Tag,同时自定义Tag的处理方式。
一想到生成Java RESTful API文档,首先就是想到Java API文档是如何生成的,所以解析源码的方式没有选择使用 com.github.javaparser » javaparser-core
或者 com.thoughtworks.qdox » qdox
,而是选择JDK自己的 Javadoc Tool ( docs.oracle.com/en/java/jav… Tool对应的API是 Javadoc API ( docs.oracle.com/en/java/jav…
由于作者还在使用 Java8 ,所以该项目的实现完全是基于 Javadoc API 旧版
其中:
Modulejdk.javadoc Package com.sun.tools.javadoc This package and its contents are deprecated and may be removed in a future release. See javax.tools. ToolProvider.getSystemDocumentationTool and javax.tools.DocumentationTool for replacement functionality.
Modulejdk.javadoc Package com.sun.javadoc Note: The declarations in this package have been superseded by those in the package jdk.javadoc.doclet . For more information, see the Migration Guide in the documentation for that package.
@Deprecated(since="9",forRemoval=true) public class Main extends Object 复制代码
可以看出,旧版Javadoc API自 Java9 已经被标记遗弃,在不久的将来将被移除,但是值得庆幸,直到最新的大版本 Java12 该API还未移除,所以使用 Java12 及以前版本的用户可以放心使用,后续作者会提供新版API支持。
UI界面是基于 create-react-app 与 antd 开发的single page application —— smalldoc-antd-react-ui ( github.com/liuhuagui/s…
示例为spring-boot项目,使用 application.yml 做为配置文件
<dependency> <groupId>com.github.liuhuagui</groupId> <artifactId>smalldoc-spring-boot-starter</artifactId> <version>2.3</version> </dependency> 复制代码
接口文档通常在开发时使用,只需要保证文档配置在开发环境下生效 —— spring.profiles.active=dev
server: port: 8080 servlet: context-path: /my-project spring: profiles: active: dev --- spring: profiles: dev smalldoc: source-paths: #额外的源码路径(项目的源码路径默认已经包含在内,不需要再添加) - 'D:/Workspaces/myBeanProject/my-bean/src/main/java' - 'D:/Maven/Repositories/repository/com/aliyun/aliyun-java-sdk-core/3.5.0' packages: - quantity.knowledgebase - my.bean - com.aliyuncs.auth.sts project-name: 我的文档 enabled: true #默认为true url-pattern: /smalldoc/* #默认为/smalldoc/* 复制代码
http://192.168.1.76:8080/my-project/smalldoc/
/** * 文章的创建,编辑,发布,自定义 * @author KaiKang 799600902@qq.com */ @RestController @RequestMapping("w") public class WriteArticleController { /** * 原创文章在编辑中保存 * @param content 内容 * @param oaCopy 原创文章副本 * @return data-草稿ID * @author KaiKang 799600902@qq.com */ @PostMapping(path = "o/save_draft",produces = {"text/plain", "application/json;charset=UTF-8"},consumes = "application/x-www-form-urlencoded") public Result<Long> saveOriginalDraft(String content, OriginalArticleCopy oaCopy, HttpServletRequest request) { return writeArticleService.saveOriginalDraft(content, oaCopy); } /** * 这只是一个测试接口 * @param content 内容 * @return 返回数据 * @author KaiKang 799600902@qq.com */ @GetMapping(path = "o/save",produces = {"text/plain", "application/json;charset=UTF-8"}) public Result<OriginalArticle> save(String content, HttpServletRequest request) { return null; } } 复制代码
http://192.168.1.76:8080/my-project/smalldoc/