# duo-doc-demo

**Repository Path**: duoec/duo-doc-demo

## Basic Information

- **Project Name**: duo-doc-demo
- **Description**: duo-doc的演示项目
- **Primary Language**: Java
- **License**: Apache-2.0
- **Default Branch**: master
- **Homepage**: https://www.duoec.com
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2024-06-28
- **Last Updated**: 2024-06-28

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# duo-doc-demo

Hello Duo-Doc，这是一个演示项目。用于演示如何接入 `duo-doc`。

**不代表本项目的编码规范和最佳实践。**

# 一、duo-doc介绍

`duo-doc`是基于 `javadoc` 实现的自定义文档doclet，即是自动化文档构建工具。

- 基因决定它是 java 生态，仅能生成 java 项目的接口。
- 代码零入侵。不需要特殊的注解。不需要特别写注释就可以生成可读性很强的接口文档。
- 跟swagger的模式不同。javadoc是通过源码解析生成文档的工具，它在源码构建阶段触发文档生成，可以快速整合进CI过程。
- 支持JDK8及以上所有版本
- 支持SpringMVC / Dubbo / OpenFeign / Markdown
- 支持代码分支、接口代码编写人采集展示。
- 支持多种导出。包括json文件、swagger-ui、apifox...


# 二、分支说明

`duo-doc`全面支持从JDK8 至 JDK21全系列的javadoc构建，分别对应几个分支：

| 代码分支   | 适用JDK版本      | 备注                                                               |
|:-------|:-------------|:-----------------------------------------------------------------|
| master | jdk8         | JDK未引入模块化，doclet使用`com.sun`包                                     |
| jdk11  | jdk9 ~ jdk12 | JDK引入了模块化，doclet仍然使用`com.sun`包                                   |
| jdk17  | jdk13 ~ 最新版本 | 废弃了`com.sun`包，重写了`doclet`，使用了`jdk.javadoc`模块，更换了包名：`jdk.javadoc` |


# 三、duo-doc 项目介绍

`duo-doc`是Java自动化文档项目，包含几个模块：

## 2.1 duo-doclet

`duo-doclet` 基于`javadoc`实现的自定义接口信息抽取工具。
使用`javadoclet`能力，我们实现了基于源码解析出必要的接口信息。通过`Exporter`导出器，将接口信息导出成各种方式，目前支持的导出器有：
- openapi，导出到支持openapi规范（即swagger）的系统，比如swagger-ui 或 第三方的的 apifox。可以直接推向服务器或生成openapi.json文件
- 导出api.json。这是duo-doclet原生的数据结构，包含完整的数据信息。比openapi信息更完善，支持的接口类型更多（RESTFul / Dubbo / OpenFeign / Markdown ...）。基于api.json，可以扩展出其它的应用，比如 `duo-graphql`

`duo-doclet`支持扩展，可以方便定制企业的各种接口规范的`约定规则`，定制导出器，定制接口类型...

`duo-doclet`基于源码进行的解析，因此绝大部分的接口信息都是通过代码及注释获取得，所以它可实现代码零入侵。
没有swagger那样的代码注解。对于开发人员来说非常友好，只要写好代码，多写几行注释，就可以生成可读性很强的文档。

`duo-doclet`可以使用maven / gradle插件的方式，配置成在项目构建的各个阶段启动。它可以非常灵活地整合到 CI/CD 的流水线里面。

## 2.2 duo-doc-server

`duo-doc`的服务端，可以使用docker-composer快速部署。当然也可以使用 apifox 等第三方的UI进行展现。


## 2.3 duo-doc-web

`duo-doc`的Web界面，推荐使用，具有最全最完善的信息展示能力。


# 四、基于duo-doc的敏捷迭代

## 1. 敏捷中的两大类开发模式

### 1.1 接口文档先行

先定义好接口，前后端再进行代码开发。这要求在正常的迭代前多增加一个接口定义的步骤。
这一般也是因为没有像duo-doc这类工具而进行的妥协，并非是敏捷的必要过程。
对于开发人员来说，维护接口文档是一项非常枯燥且没兴趣的事。

### 1.2 自动化文档

而今，有了更好的选择。跟随代码的提交，接口文档自动生成。即保证了文档的及时性，还不需要开发人员额外去维护。


## 2. 真正的敏捷

### 2.1 产品经理开完需求评审

#### 2.1.1 后端人员根据需求文档快速完成技术设计

第一阶段：需求数据、数据流的设计。本阶段主要对实现需求功能进行数据流层面的设计。

包括数据表的设计、数据的流存、功能的实现等

第二阶段： 接口设计...

通常，数据表结构确定好之后，这个环节很大部分的工作都可以通过工具快速生成。

比如从数据库到controller的各种类、基础CURD方法及接口。所以，在这一步，开发人员已经可以快速实现接口的定义。

第三阶段：完成接口文档，进行技术评审

接口定义完成后，提交代码到迭代分支，CI构建触发duo-doc文档的构建，并提交到duo-doc。

构建完成后，前端端人员就可以在duo-doc web界面上查看到最新的接口文档。

技术评审就可以开始了，技术评审环节，后端进行技术实现、接口入参、接口响应讲解。

通过接口文档与前端一个个功能，一个个字段核对，从而提出达成共识。


第三阶段：接口实现


#### 2.1.2 前端人员快速进行界面开发

第一阶段：静态页面编写，主要完成界面的布局、用户交互

第二阶段：接口对接

当接口文档提交到 duo-doc，即便后端尚未写实现接口功能，duo-doc的mock能力就已经准备好了。前端可以通过真实的请求（加上请求头：mock:1）进行访问。
所以整个流程，前端的开发是不会受到阻碍的

第三阶段：接口联调

接口联调是在接口已经实现的基础上进行的。后端人员根据接口文档与技术评审阶段达成的共识进行开发。

原则上，严格按接口文档来实现接口，前端可以直接去掉请求头的mock:1，调用到动态的接口数据。不需要更改其它任何代码！


# 五、接入duo-doc

JDK17及以上接入案例，其它JDK版本请参考上面的表格

```xml
<!-- JDK 8 使用，JDK未引入模块化，doclet使用com.sun包 -->
<build>
    <plugins>
        <!-- 重要！Duo-Doc，通过解析源码、注释自动生成接口信息 -->
        <plugin>
            <groupId>org.apache.maven.plugins</groupId>
            <artifactId>maven-javadoc-plugin</artifactId>
            <version>3.3.1</version> <!-- 各版本的参数不一致，建议不要改版本 -->
            <configuration>
                <doclet>com.duoec.doc.DuoDoclet</doclet>
                <docletArtifact>
                    <groupId>com.duoec</groupId>
                    <artifactId>duo-doclet-8</artifactId>
                    <version>1.0.5</version> <!-- 请使用最新版本 -->
                </docletArtifact>

                <useStandardDocletOptions>false</useStandardDocletOptions>
                <includeDependencySources>true</includeDependencySources>
                <includeTransitiveDependencySources>true</includeTransitiveDependencySources>
                <dependencySourceIncludes>
                    <dependencySourceInclude>com.duoec*:*</dependencySourceInclude> <!-- 需要引入三方包源码的坐标（支持通配符） -->
                </dependencySourceIncludes>

                <additionalOptions>
                    <additionalOption>-doc.basePath ${project.basedir}</additionalOption>
                    <additionalOption>-doc.exporter.server https://doc.duoec.com</additionalOption>
                </additionalOptions>
            </configuration>
            <executions>
                <execution>
                    <id>attach-javadocs</id>
                    <!-- 文档构建的阶段，比如配置为compile，由执行以下命令即可触发：mvn clear compile -->
                    <phase>compile</phase>
                    <goals>
                        <goal>javadoc</goal>
                    </goals>
                </execution>
            </executions>
        </plugin>
    </plugins>
</build>
```