Camunda Platform REST API OpenAPI 文档自动生成:基于 FreeMarker 模板的 openapi.json 构建体系

原创2026-09-17 16:44:522,163 阅读
文章标签:后端工作流自动化流程编排

Camunda Platform REST API OpenAPI 文档自动生成:基于 FreeMarker 模板的 openapi.json 构建体系

导读

本文围绕 Camunda Platform(camunda-bpm-platform)仓库中的 engine-rest/engine-rest-openapi 模块,系统讲解 Camunda REST API 的 OpenAPI 3.0.2 文档是如何"从源码模板自动生成"的:包括 mvn clean install 触发的四阶段构建流水线、FreeMarker 模板的目录结构与编写规范(main.ftl、lib/utils.ftl、models、paths、commons)、宏(macro)体系的设计意图,以及评审(Review)与质量保障流程。读完本文,你将掌握如何为一个新的 REST 端点添加 OpenAPI 描述、如何正确使用 parameter/property/requestBody/response 等宏、如何通过排序/分页公共模板保持文档一致性,并理解生成出的 openapi.json 如何反向驱动 Java Client 生成与 WireMock 冒烟测试。

一、模块定位:一份 openapi.json 覆盖整个 Engine REST API

engine-rest/engine-rest-openapi 是 Camunda Platform 中专门负责 OpenAPI 文档生成 的 Maven 模块(artifactId 为 camunda-engine-rest-openapi)。它的核心目标非常单一:

解析一组 FreeMarker 模板,生成一份格式化良好的 openapi.json,其中包含 Camunda Engine REST API 的完整 OpenAPI 文档。

该文档对齐 OpenAPI Specification 3.0.2(OpenAPI 3.0.2 规范中的 info、servers、tags、paths、components/schemas、securitySchemes 等对象均在生成结果中体现)。

从 pom.xml 可以看到,模块还依赖同仓库的 camunda-engine-rest-openapi-generator 模块(TemplateParser、SchemaValidator 两个 Java 类),并声明了 openapi-generator-maven-plugin、WireMock、AssertJ 等测试依赖。模块当前处于 7.24.0-SNAPSHOT 版本(仓库快照版本,实际发布版本以仓库 pom 为准)。

二、构建流水线:一次 mvn clean install 的四阶段

原文档明确指出构建命令为:

mvn clean install

在 pom.xml 中,构建被编排为四个相互衔接的阶段,全部通过 Maven 插件绑定到生命周期中:

阶段 1:模板解析,生成格式化 openapi.json

exec-maven-plugin 的 generate-openapi-json 执行体绑定在 generate-resources 阶段,调用主类 org.camunda.bpm.engine.rest.openapi.generator.impl.TemplateParser,参数为:

  • ${project.basedir}/src/main/templates(模板源目录)
  • main.ftl(主模板入口)
  • ${generated-directory}/openapi.json(输出文件,即 target/generated-sources/openapi-json/openapi.json)
  • ${project.build.directory}(中间调试输出目录)

从 TemplateParser.java 的实现可以看到完整处理流程:

  1. 使用 FreeMarker Configuration.VERSION_2_3_29 加载 main.ftl 模板;
  2. createTemplateData() 扫描模板目录,构建模板数据模型:models(DTO 名 → 包路径的映射,按名称字典序排序)与 endpoints(端点路径 → HTTP 方法列表的映射,同样字典序排序);
  3. 模板渲染后,先写出一份带时间戳的 intermediate-openapi-*.json 中间文件(便于调试),再用 Gson(setPrettyPrinting() + serializeNulls())对 JSON 进行格式化并落盘为最终 openapi.json。

值得注意的是路径解析约定(resolvePaths):端点的 URL 路径直接从文件系统的目录结构推导——例如 src/main/templates/paths/process-instance/count/get.ftl 会被解析为 GET /process-instance/count。模板文件名(去掉 .ftl 后缀)即 HTTP 方法名。

阶段 2:Schema 校验

同一阶段的 validate-openapi-json 执行体调用 org.camunda.bpm.engine.rest.openapi.generator.impl.SchemaValidator,使用仓库内置的 schema.json(OpenAPI 3.0 官方 JSON Schema 的本地副本,取自 2020-02-11)对生成的 openapi.json 做结构校验。

SchemaValidator.java 使用 networknt 的 JsonSchemaFactory 加载 schema 并 validate() 生成的文档,一旦出现任何 ValidationMessage 错误,直接抛出 RuntimeException("Schema validation errors\n" + messages),使构建失败。这保证了模板变更不会产出结构非法的 OpenAPI 文档。

阶段 3:从 openapi.json 生成 Java Client

openapi-generator-maven-plugin(版本 4.2.3)的 generate-java-client 执行体绑定在 generate-test-sources 阶段,以刚生成的 openapi.json 为输入(inputSpec),输出到 target/camunda-openapi-client,generatorName=java,并配置 dateLibrary=legacy。随后 build-helper-maven-plugin 把生成的客户端源码加入测试源码目录。这一阶段意味着:每改动一次模板,都会立即重新生成一份可编译的 Java Client,作为文档"可消费性"的即时验证。

阶段 4:针对生成客户端的冒烟测试

测试代码位于 engine-rest/engine-rest-openapi/src/test,使用 WireMock 对生成的客户端做冒烟测试,例如:

  • DeploymentTest.java(部署相关端点)
  • ProcessInstanceTest.java(流程实例相关端点)
  • BasicAuthenticationTest.java(基础认证流程)

这些测试用 WireMock 模拟真实 REST 服务,再通过生成的 Java Client 发起调用,从而验证"OpenAPI 文档 → 客户端 → 实际 HTTP 语义"整条链路的正确性。pom 中的 swagger-annotations、okhttp、gson、gson-fire、jsr305、commons-lang3 等依赖正是生成客户端运行所需的支撑库。

三、模板目录结构:文档的"源代码"

OpenAPI 文档本身是产物,FreeMarker 模板才是真正的"源代码"。原文档给出的模板结构如下(对应 src/main/templates 目录):

 +--main.ftl
 +--lib
 | +--utils.ftl
 | +--commons
 | | +--pagination-params.ftl
 | | +--process-instance-query-params.ftl
 | | +--sort-params.ftl
 | | +--sort-props.ftl
 +--models
 | +--org/camunda/bpm/engine/rest/dto
 | | +--ExceptionDto.ftl
 | | +--history
 | | | +--HistoricProcessInstanceQueryDto.ftl
 | | +--repository
 | | | +--DeploymentDto.ftl
 | | | +--ProcessDefinitionDto.ftl
 | | +--runtime
 | | | +--ActivityInstanceDto.ftl
 +--paths
 | +--deployment
 | | +--create
 | | | +--post.ftl
 | +--process-instance
 | | +--get.ftl
 | | +--suspended
 | | | +--put.ftl
 | | +--{id}
 | | | +--delete.ftl
 | | | +--variables
 | | | | +--{varName}
 | | | | | +--data
 | | | | | | +--get.ftl
 | | | | | | +--post.ftl
 | | | | | +--delete.ftl

实际仓库中的目录比文档示例更庞大:lib/commons 下有约 40 个可复用模板(task-query-params.ftl、historic-incident-query-params.ftl、statistics-query-params.ftl、deployment-query-params.ftl 等);paths 下按资源组织了几十个子目录(authorization、batch、deployment、execution、external-task、history、process-instance、process-definition、task 等);models/org/camunda/bpm/engine/rest/dto 下有约 195 个 DTO 模板。

各部分的职责划分如下:

目录/文件 职责
main.ftl OpenAPI 文档顶层骨架:版本、info、servers、tags、paths、components
lib/utils.ftl 全部宏(macro)的定义,路径与模型模板共同使用
lib/commons/*.ftl 可复用的参数/属性片段(分页、排序、各类查询参数)
models/... 请求/响应体引用的 DTO 定义,目录结构与 Java 包名对齐
paths/... 每个 REST 端点的操作定义,目录结构即 URL 路径

四、main.ftl:OpenAPI 文档的顶层骨架

main.ftl 是模板解析的入口(在 pom 中作为第二个参数传给 TemplateParser)。它负责输出 OpenAPI 3.0.2 文档的全局信息:

  • openapi 版本:固定输出 "openapi": "3.0.2";
  • info:标题 Camunda Platform REST API、描述、版本 ${cambpmVersion}(来自 Jar 包的 ImplementationVersion)、License(Apache License 2.0);
  • externalDocs:指向 Camunda REST API 参考文档;
  • servers:通过 lib.server 宏输出三种服务端地址——默认引擎(http://{host}:{port}/{contextPath},默认 localhost:8080/engine-rest)、命名引擎(含 /engine/{engineName} 路径变量)、自定义 URL 服务器;
  • tags:为每个资源定义一个标签(共 50 个左右),如 Authorization、Deployment、Process Instance、Task、Task Attachment、Task Comment、Task Identity Link、Historic Process Instance 等。子资源必须使用父资源标签作为前缀(如 Task 与 Task Attachment);
  • paths:遍历 endpoints 数据模型,对每个 URL 路径、每个 HTTP 方法导入对应的 <method>.ftl 并调用其 endpoint_macro;
  • security / components:声明 basicAuth HTTP 基础认证安全方案;components/schemas 遍历 models 数据模型,对每个 DTO 导入对应模板并调用其 dto_macro。

main.ftl 还定义了文档链接的基础变量 docsUrl = "https://docs.camunda.org/manual/${docsVersion}",其中 docsVersion 由 TemplateParser.resolveVersions 根据包版本推导:SNAPSHOT 版本映射为 develop,alpha 版本映射为 latest,正式版本则取 7.x 前缀——这是模板内大量 `User guide 是整个生成体系的"标准库",定义了路径与模型模板中高频使用的宏:

宏 用途 关键参数
parameter 生成查询/路径参数的 JSON 对象 name、location、type、desc,可选 enumValues、defaultValue、format、required、last
parameters 批量生成一组查询参数 object(参数集合)、skip(跳过列表)、last
property 生成 DTO 属性的 JSON 对象 name、type,可选 format、nullable、enumValues、minimum、deprecated、itemType、dto、additionalProperties、addProperty、last
properties 批量生成一组属性 同上
dto 生成 DTO 的 schema 定义 type、title、desc、required、extends(触发 allOf 继承)
requestBody 生成请求体 mediaType、dto/flatType、requestDesc、examples
response 生成 HTTP 响应对象 code、desc,可选 dto、array、additionalProperties、mediaType、binary、examples、last
multiTypeResponse 生成多 content-type 的响应 types 数组
server 生成 server 对象 url、variables、desc
endpointInfo 生成操作的元信息 id(operationId)、tag、desc,可选 deprecated、summary
removeIndentation 函数,压缩描述中的多级缩进 文本

几个需要重点理解的实现细节:

  1. 逗号(,)控制:所有宏都以 last 参数控制 JSON 对象间的逗号输出——最后一个条目传 last = true 时不输出逗号,其余输出。这是保证最终 JSON 语法正确的关键约定,原文档反复强调不要遗漏。
  2. nullable 的默认策略:property 宏 中,当类型为 boolean、string、array 或带有 format、dto 引用时,nullable 默认输出 "nullable": true,目的是兼容 C# 客户端对"字段是否可为 null"的显式声明需求;只有确定必填的属性才通过 nullable = false 关闭。
  3. type=ref:property 宏支持 type = "ref" + dto = "xxx" 输出 $ref 指向 #/components/schemas/xxx;array 与 additionalProperties 组合支持输出 items/additionalProperties 的内联对象或 $ref。
  4. 204 响应:response 宏 对 204 No Content 不生成 content 块;responseContentMediaType 对 application/xhtml+xml、二进制流等媒体类型输出 format: binary 的字节流 schema。
  5. server 宏:通过 FreeMarker 的 <#list variables as name, default> 遍历输出带默认值的 URL 变量。

原文档特别提醒:这些宏在路径与模型模板中被大量使用,建议先熟悉它们;但如果某个端点/DTO 过于复杂,不使用宏、手写 JSON 也是允许的。宏缺少参数时可以直接补充,但必须同步修改所有调用点。部分参数是强制的(多数场景下的 name 与 description),部分是可选的锦上添花参数(minimum、defaultValue、deprecated)。

六、models:DTO 定义的编写规范

models 目录存放请求/响应体中出现的所有 DTO,且遵循以下约定:

  • 命名与包结构对齐 Java DTO:例如 Java 类 org.camunda.bpm.engine.rest.dto.ExceptionDto.java(位于 engine-rest/engine-rest/src/main/java/org/camunda/bpm/engine/rest/dto/ExceptionDto.java)对应模板 models/org/camunda/bpm/engine/rest/dto/ExceptionDto.ftl,保持 OpenAPI 属性与 Java DTO 尽可能一致;当某属性对特定端点不适用时,在端点描述中显式说明(例如 process-instance/suspended/put.ftl 中 ProcessInstanceSuspensionStateDto 的 historicProcessInstanceQuery 属性在批量暂停场景的适用性说明)。
  • 模型自动解析:TemplateParser.resolveModels() 递归扫描 models 目录,从文件路径中的 org 包名截取包路径,模型按名称字典序自动排序。因此 /models 目录只放文档中实际用到的模型;宏与可复用片段必须放进 lib/commons;禁止创建空目录。
  • 用 dto 宏定义模型:所有 DTO 模板都应通过 dto 宏包裹 property 宏。对于存在继承关系的 DTO(如 TriggerVariableValueDto extends VariableValueDto),dto 宏的 extends 属性会生成 OpenAPI 的 allOf 语法。仓库示例 TriggerVariableValueDto.ftl:
<#macro dto_macro docsUrl="">
<@lib.dto
    extends = "VariableValueDto" >

        <@lib.property
            name = "local"
            type = "boolean"
            last = true
            desc = "Indicates whether the variable should be a local variable or not.
                    If set to true, the variable becomes a local variable of the execution
                    entering the target activity." />

</@lib.dto>
</#macro>

渲染后即生成 {"allOf": [ {...本地属性...}, {"$ref": "#/components/schemas/VariableValueDto"} ]}。

  • 响应可能是两种 DTO 的情况:当响应的具体 DTO 取决于请求参数时(如消息关联 MessageCorrelationResultDto 与其子类 MessageCorrelationResultWithVariableDto),建议直接使用包含全部属性的那个 DTO 作为响应 schema,并明确记录哪些属性在哪些场景不适用。原文档提示:某些场景可考虑 oneOf + discriminator(OpenAPI 3.0.2 支持),但必须额外测试,因为部分客户端生成器对该写法支持不佳。
  • 不要忘记 last = true:每个 property 宏的最后一个属性必须传 last = true,由宏负责 JSON 逗号。
  • 含排序/分页的 DTO:应复用 lib/commons 中的公共模板(见下文)。

七、paths:端点定义的编写规范

paths 目录存放 REST API 全部端点的操作定义,核心规则如下:

  • 目录结构即 URL 路径:每个资源一个文件夹(如 /paths/process-instance、/paths/deployment)。端点路径由目录自动推导——GET /process-instance/count 对应 /paths/process-instance/count/get.ftl。因此必须保持 /paths 目录干净,除端点定义外不放任何多余文件(可复用片段一律进 lib/commons),同样禁止空目录;端点路径按字典序自动排序。
  • HTTP 方法即模板文件名:get.ftl、post.ftl、put.ftl、delete.ftl、options.ftl(原文档示例中写为 post.frl,系笔误,实际为 post.ftl)。
  • 动态路径参数:动态端点用花括号目录表达,如 process-instance/{id}/variables/{varName}/data,且路径参数(id、varName)必须出现在端点定义中并标记为 required(通过 parameter 宏的 location = "path" 与 required = true)。
  • operationId 唯一:每个端点定义必须有唯一的 operationId,它直接用于客户端生成。大多数情况下直接采用 Java 方法名(如 deleteProcessInstancesAsync);无法采用时按 Java 命名规范自定义。
  • async 端点的 C# 碰撞规避:对异步端点,在 operationId 后追加 Operation 后缀,防止 C# 客户端生成时与同步方法冲突。原文档示例:setExternalTaskRetriesAsync → setExternalTaskRetriesAsyncOperation,modifyProcessInstanceAsync → modifyProcessInstanceAsyncOperation。
  • 相似端点拆分:路径不同但几乎相同的端点(如"获取活动实例统计"在不同资源下的变体)必须拆分为不同文件,并各自分配唯一 operationId,公共部分可抽到 lib/commons。
  • 必填的内容要素:每个端点必须包含——所属资源的 tag(如 Process instance、Deployment);description 与 summary(summary 通常对应 REST API 文档页标题);至少一个 HTTP 响应对象;请求体尽量使用 DTO(始终先查看对应 Java DTO 的字段,避免只靠端点描述拼凑无 DTO 的请求体)。

以 process-instance/suspended/put.ftl 为完整范例,可以看到 endpointInfo + requestBody(带 3 个示例)+ responses(204 与 400,ExceptionDto)的典型组合:

<#macro endpoint_macro docsUrl="">
{
  <@lib.endpointInfo
      id = "updateSuspensionState"
      tag = "Process Instance"
      summary = "Activate/Suspend In Group"
      desc = "Activates or suspends process instances by providing certain criteria: ..." />

  <@lib.requestBody
      mediaType = "application/json"
      dto = "ProcessInstanceSuspensionStateDto"
      examples = ['"example-1": {
                     "summary": "PUT `/process-instance/suspended`",
                     "description": "Suspend Process Instance By Process Definition Id",
                     "value": {
                       "processDefinitionId" : "aProcDefId",
                       "suspended" : true
                     }
                   }', ...] />

  "responses" : {
    <@lib.response code = "204" desc = "Request successful."/>
    <@lib.response code = "400"
        dto = "ExceptionDto"
        last = true
        desc = "Bad Request ..."/>
  }
}
</#macro>

八、commons:排序、分页与复用

lib/commons 存放可复用的公共模板,原文档重点介绍了三类:

1. 排序(sorting)

使用方式:先 assign 一个 sortByValues 枚举列表,再 #include 对应模板;若该排序属性是最后一个参数/属性,还需取消注释 last = true。原文档示例:

<#-- <#assign last = true >  -->  <#-- remove comment if last param  -->
<#assign sortByValues = ['"instanceId"', '"definitionId"', '"definitionKey"', '"definitionName"', '"definitionVersion"', '"businessKey"', '"startTime"', '"endTime"', '"duration"', '"tenantId"']>
<#include "/lib/commons/sort-props.ftl" >

从 sort-props.ftl 的实现可以看到,该模板输出 sortBy(枚举来自 sortByValues)与 sortOrder(枚举固定为 asc/desc)两个属性;若传了 sortParamsDto,还会追加一个 parameters 引用属性。模板注释解释了设计缘由:sortBy 的取值必须动态定义,且不同 Query 端点的排序属性集合不同,因此不能写死在 dto 宏里,而必须显式 #include。

2. 分页(pagination)

只要端点参数包含 firstResult 与 maxResults 就应使用它。从 pagination-params.ftl 的实现可见它输出两个 integer 类型的查询参数:firstResult(返回结果的起始索引)与 maxResults(最多返回条数,超出时返回较少结果)。使用方式同样是先设定 last 再 include:

    <#-- <#assign last = true >  -->  <#-- remove comment if last param  -->
    <#include "/lib/commons/pagination-params.ftl" >

3. 复用(reuse)

当同一组参数在多个端点反复出现时,可自定义模板并复用。原文档给出的范例是 process-instance-query-params.ftl,被 getProcessInstancesCount 与 getProcessInstances 两个端点共同引用。仓库中这样的模板非常多,例如 task-query-params.ftl、external-task-query-params.ftl、historic-process-instance-query-params.ftl、authorization-query-params.ftl、deserialize-values-parameter.ftl 等,它们保证了同类查询端点参数描述的一致性。

九、描述、格式、可空性与示例:写作文档的四个关键规范

1. 描述文本(Descriptions)

描述支持 Markdown 语法:`monospace`(代码)、*italic* / _italic_(斜体)、**bold** / __bold__(粗体)、* bullet point(列表)。文本规范包括:

  • 使用 Unix 换行符(LF);
  • 链接使用 Markdown 语法;
  • 通过 ${docsUrl} 变量解析官方文档链接(docsUrl 在 main.ftl 中定义为 https://docs.camunda.org/manual/${docsVersion}),例如 User guide;
  • 单行长度不超过 120 字符;
  • 使用缩进与换行拆分长描述,提升可读性,模板渲染时会由 removeIndentation 函数统一压缩缩进。原文档示例(流程实例修改指令端点):
  "description": "Submits a list of modification instructions to change a process instance's execution state.
                  A modification instruction is one of the following:

                  * Starting execution before an activity
                  * Starting execution after an activity on its single outgoing sequence flow
                  * Starting execution on a specific sequence flow
                  * Canceling an activity instance, transition instance, or all instances (activity or transition) for an activity

                  Instructions are executed immediately and in the order they are provided in this request's body.
                  Variables can be provided with every starting instruction.

                  The exact semantics of modification can be read about in the [User guide](https://docs.camunda.org/manual/develop/user-guide/process-engine/process-instance-modification/)."

2. 格式(Formats)

format 字段进一步限定属性/参数的类型语义(详见 OpenAPI 3.0.2 规范的 dataTypeFormat)。本仓库文档常用的格式为 int32、binary、date-time。例如日期属性一律标注 date-time 格式:

    <@lib.property
        name = "startedBefore"
        type = "string"
        format = "date-time"
        description = "Restrict to instances that were started before the given date.
                       By default (https://docs.camunda.org/manual/${docsVersion}/reference/rest/overview/date-format/),
                       the date must have the format `yyyy-MM-dd'T'HH:mm:ss.SSSZ`, e.g., 2013-01-23T14:42:45.000+0200." />

标注 format 能显著提升生成客户端的可用性。特别注意:当 date-time 出现在 GET 请求的 URL 参数中时,必须按 Camunda 的日期格式约定做正确的 URL 编码。

3. 可空性(Nullable)

默认情况下,boolean、string、array、dto 类型的属性会自动开启 nullable: true,以生成对 C# 客户端更友好的宽松规范(字段是否可为 null 由客户端显式声明)。只有在确定必填的属性上才显式关闭:

    <@lib.property
         name = "version"
         type = "integer"
         format = "int32"
         nullable = false
         desc = "The version of the process definition that the engine assigned to it." />

4. 示例(Examples)

requestBody 与 response 宏都支持 examples 参数,约定如下:

  • 示例内容用单引号包裹(而非双引号),因为示例内包含引号需要转义;
  • 允许多个示例,每个示例是 examples 数组中的一个独立 JSON 对象(如 example-1、example-2);
  • 每个示例必须有唯一名称;
  • 可添加 description 与/或 summary;
  • value 属性必填,承载示例内容。

原文档示例(为 SetJobRetriesByProcessDto 请求体配置示例,并说明 historicProcessInstanceQuery 在该场景下是 Unallowed property):

  <@lib.requestBody
      mediaType = "application/json"
      dto = "SetJobRetriesByProcessDto"
      requestDesc = "Please note that if both processInstances and processInstanceQuery are provided,
                     then the resulting execution will be performed on the union of these sets.
                     **Unallowed property**: `historicProcessInstanceQuery`"
      examples = ['"example-1": {
                       "value": {
                         "retries": numberOfRetries,
                         "processInstances": ["aProcess", "secondProcess"],
                         "processInstanceQuery": {
                           "processDefinitionId": "aProcessDefinitionId"
                         }
                       }
                    }'/>

十、Reviews:模板变更的质量评审清单

由于 OpenAPI 文档是由目录结构与模板间接推导的,错误的路径、缺失的响应、不规范的 operationId 都不易直接察觉,因此原文档给出了一套评审(Review)清单:

  1. 宏变更回归:若修改了 utils.ftl 中的宏,请将上次构建的 openapi.json 与本次待评审版本做对比,确保所有端点在新宏下仍然完整;
  2. 核对端点路径:路径由目录结构推导,肉眼不易发现错误,必须逐条额外核对;
  3. 核对参数、请求与响应:确保参数、请求体、响应对象正确;
  4. 与 Java 端点对齐:operationId 应尽可能贴近 DTO 包中对应的 Java 方法(对照 *RestService.java 与 *Resource.java 接口,如 engine-rest/engine-rest/src/main/java 下的实现);
  5. 客户端对比:可将构建阶段生成的客户端与真实 REST API 对比,多数情况下两者应该高度相似。

十一、从模板到可发布产物的闭环

综合来看,camunda-engine-rest-openapi 模块形成了一条完整的"文档即代码"闭环:

  1. 贡献者按规范在 paths、models、lib/commons 中编写/修改 FreeMarker 模板;
  2. mvn clean install 时 TemplateParser 基于目录结构自动推导端点路径与模型清单,渲染出 openapi.json;
  3. SchemaValidator 用 OpenAPI 3.0 官方 schema 本地副本校验结构合法性,非法即构建失败;
  4. openapi-generator-maven-plugin 依据 openapi.json 生成 Java Client 源码;
  5. WireMock + JUnit 冒烟测试验证客户端行为(DeploymentTest、ProcessInstanceTest、BasicAuthenticationTest 等);
  6. 生成的 openapi.json 同时作为模块资源(build-helper-maven-plugin 将其加入资源目录)随制品发布,供下游工具消费。

这一体系的价值在于:REST API 文档不再是与实现脱节的静态文件,而是与端点源码、DTO 结构严格对齐、且每轮构建都被机器验证的"活文档"。对于需要为 Camunda Platform 扩展自定义 REST 端点、或希望理解大型项目如何用模板化方式维护 OpenAPI 规范的开发者,engine-rest/engine-rest-openapi 是一份极具参考价值的实现样本——其模板组织方式、宏抽象粒度、公共片段复用策略与"生成—校验—生成客户端—冒烟测试"的构建编排,都可以直接迁移到同类项目中复用。

登录后查看全文
camunda-bpm-platform