v1.x文档
快速入门

快速开始

我们将通过一个简单的 Demo (opens new window) (推荐您直接下载运行) 来阐述 doc-apis 的强大功能，在此之前，我们假设您已经：

拥有 Java 开发环境以及相应 IDE
熟悉 Spring Boot (推荐版本2.5.x +)
熟悉 Maven

特别注意

由于框架内引用了fastjson,所以如果您的项目中已经存fastjson,需要您先排除doc-apis中的fastjson依赖或统一版本,避免因依赖冲突导致无法正常生成接口文档

# 初始化工程

创建一个空的 Spring Boot 工程

提示

可以使用 Spring Initializer (opens new window)快速初始化一个 Spring Boot 工程

# 添加依赖

Maven:

        <!-- 引入doc-apis最新版本的依赖-->
        <dependency>
            <groupId>com.doc-apis</groupId>
            <artifactId>doc-apis-starter</artifactId>
            <!--这里Latest Version是指最新版本的依赖,比如2.0.0,可以通过下面的图片获取-->
            <version>Latest Version</version>
            <!--下面这段可选,如果您不希望doc-apis打包进您的项目中,通过test模块启动项目自动生成接口文档也是可以的-->
            <!--<scope>test</scope>-->
        </dependency>

1
2
3
4
5
6
7
8
9

Gradle:

compile group: 'com.doc-apis', name: 'doc-apis-starter', version: 'Latest Version'

# ✨最新版本 Latest Version: (opens new window)

# 配置

如果您是单模块项目,或模块深度<=1,则您无需任何配置,如果您的Controller层分散在各个模块中,则需要您手动加1行配置：

doc-apis:
  project-path: ${your project module path} #例如 hutool有多个模块,代码存在E盘,但仅aop模块需要生成文档,则配置到具体模块 E:\hutool\hutool-aop 如有多个模块,用逗号隔开即可

1
2

后面有章节详细介绍doc-apis的所有配置

# 开始使用(一键生成)

1.编写您的Controller接口,如果您项目已经写好Controller,则可跳过此步骤

/**
 * 示例模块
 **/
@RestController
public class SampleController {

    /**
     * 分页获取文档列表
     *
     * @param docQuery
     * @return
     */
    @PostMapping("/pageListDocs")
    public PageInfo<Document> pageListDocs(@RequestBody DocQuery docQuery) {
        return new PageInfo<>();
    }
}

/**
 * 文档
 **/
@Data
public class Document {
    /**
     * 主键
     */
    private Long id;
    /**
     * 文档标题
     */
    private String title;
}

/**
 * 文档查询入参参数
 */
@Data
public class DocQuery {
    /**
     * 标题
     */
    private String title;
    /**
     * 作者
     */
    private String author;
    /**
     * 当前页
     */
    private int pageNum;
    /**
     * 每页显示条数
     */
    private int pageSize;
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56

2.点击IDEA或Eclipse等编辑器,启动当前项目,然后待控制台打印xxx done! 此时终止项目即可马上看到项目所在路径下已经生成一份接口文档,或者不终止项目静待一段时间(IDEA缓存刷新比较慢)也可以看到.

生成的接口文档如图: