一个极简的Java RESTful API文档工具smalldoc

项目

• github.com/liuhuagui/s… 一个基于Java标准注释的 RESTful API 文档工具
• smalldoc-antd-react-ui（github.com/liuhuagui/s…

为何要造轮子？

• 强迫症患者，接受不了Swagger的各式注解对代码的入侵形成的冗杂，更渴望清洁的代码；
• 注解的使用须要必定的学习成本；
• 随后尝试使用Apidoc，尽管Apidoc是基于注释生成文档，可是学习成本并无下降，你须要学习额外的注释Tag，同时你不得不使用这些特殊的Tag将你所需接口的相关信息手动写出来，感受并无大幅度下降书写文档的工做量；
• 也有一些基于Java标准注释生成文档的项目，可是有的没法支持实体参数、泛型变量、多模块依赖，有的Bug太多，UI界面不够友好，使用方式过于复杂，甚至逻辑处理上存在问题。

特性

• 基于Java源码、标准注释以及Tag生成文档，无代码入侵，保证代码整洁，同时保证开发人员的注释习惯与注释规范
• 提供了友好的默认UI
• 提供了文档RESTEful API，支持实现自定义UI
• 提供规范配置方式，使用更方便
• 提供相应的spring-boot-starter，同时支持传统spring与spring-boot
• 支持关联实体参数
• 支持泛型
• 支持忽略某个参数
• 支持忽略解析指定包或指定类型参数的数据结构
• 支持多模块项目（从指定Jar包中解析源码或数据结构）

实现方式

• 解析源码文件，经过源码及其中的注释生成文档信息。目前为止注释中使用的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 旧版

  • Package com.sun.tools.javadoc (docs.oracle.com/en/java/jav…)
  • Package com.sun.javadoc (docs.oracle.com/en/java/jav…)

  其中：

  Module jdk.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.

  Module jdk.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/*
复制代码

访问地址

• URL: http://192.168.1.76:8080/my-project/smalldoc/
• METHOD: GET

接口源码

/** * 文章的建立，编辑，发布，自定义 * @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;
    }
}
复制代码

接口文档

文档API（用来实现自定义UI）

• URL: http://192.168.1.76:8080/my-project/smalldoc/
• METHOD: POST

  

注意

• source-paths 配置项表示额外的源码路径，项目的源码路径默认已经包含在内，不须要额外添加，只须要指定扫描的包，好比：my.project.controller
• 程序只会解析类名为*Controller的源代码中的接口信息（规范）
• 程序暂未支持Linux环境，在项目打包部署以前，记得关闭文档功能，关闭方式多种多样，好比：
  1. spring.profiles.active=*(* 只要不是dev便可)，再也不激活开发环境配置
  2. smalldoc.enabled=false，关闭启用
  3. 修改依赖做用域为test后再进行打包，这样连smalldoc的jar包都不会被打包进去（推荐）

     <dependency>
        	<groupId>com.github.liuhuagui</groupId>
        	<artifactId>smalldoc-spring-boot-starter</artifactId>
        	<version>2.3</version>
        	<scope>test</scope>
      </dependency>
     复制代码

社区

若是在使用过程当中须要帮助或者但愿项目增长某些功能，欢迎issue —— github.com/liuhuagui/s…