生成接口文档

本节将详细介绍如何利用 Apifox helper 来生成全面且精确的接口文档。

1. 配置控制器类

首先，我们需要正确配置控制器类。在类级别的 Javadoc 中，我们可以定义文件名称和项目归属：

@RestController 注解表明这是一个 RESTful Web 服务的控制器。

@RequestMapping(value = "/pathOfCtrl") 定义了该控制器的基本 URL 路径。

类级 Javadoc 注释用于生成 API 的分类信息及项目模块归属。

注释的第一行将作为文件名称，如果使用 “父目录/文件名称” 的格式编写，将自动生成对应的文件夹结构，实现文档的层次化组织。

@module 标签指定 API 所属的项目。

2. 定义 API 方法

对于每个 API 方法，我们需要提供详细的 Javadoc 注释：

方法名称

方法名（如methodName1）通常用作 API 操作的标识符。

路径

路径由类级别的@RequestMapping和方法级别的@RequestMapping（或@GetMapping, @PostMapping等）组合而成。

完整路径：/pathOfCtrl/pathOfApi1

HTTP 方法

默认为 GET

可通过@RequestMapping(method = RequestMethod.POST)或直接使用@PostMapping等指定

请求参数

从方法参数和 Javadoc 的@param标签中提取

@RequestParam(required = false) 表示可选参数

defaultValue 属性指定默认值

响应

从@return Javadoc 标签中提取响应描述

3. 请求体参数

对于使用请求体的 API，我们可以这样定义：

默认使用query

当使用@RequestBody注解时，Apifox helper 会自动识别并设置 Content-Type 为application/json。

4. API 废弃标记

可以使用@Deprecated注解或@deprecated Javadoc 标签来标记将废弃的 API：

示例

以下是一个 Java 代码示例，以及与之相对应的 API spec：

1. 配置控制器类#

2. 定义 API 方法#

方法名称#

路径#

HTTP 方法#

请求参数#

响应#

3. 请求体参数#

4. API 废弃标记#

示例#

代码示例#

生成的 API Spec（OpenAPI 3.0）#