Flowable OpenAPI 规范自动生成指南用 flowable-oas-generator 从源码产出 Swagger/OpenAPI 定义【免费下载链接】flowable-engineA compact and highly efficient workflow and Business Process Management (BPM) platform for developers, system admins and business users.项目地址: https://gitcode.com/GitHub_Trending/fl/flowable-engineFlowable 引擎为开发者提供了覆盖 Process、Decision、CMMN 等模块的完整 REST API而与之配套的 OpenAPI/Swagger 接口描述文件则可以通过flowable-oas-generator这一 Maven 工具项目直接从 Java 源码自动生成免去手工编写接口文档的重复劳动。本文将以 flowable-oas-generator/README.md 为主体结合其 pom.xml 与 assembly.xml 等仓库文件完整讲解该工具的定位、三种典型构建命令、Maven Profile 切换机制、核心配置项含义以及生成产物在仓库中的落地方式帮助你理解并复现 Flowable 官方 OpenAPI 文档的生产链路。工具定位为 Flowable REST API 自动生成 Swagger 定义flowable-oas-generator是 Flowable 仓库中一个纯粹的工具型Maven 子项目见 pom.xmlartifactId为flowable-oas-generator父 POM 为flowable-parent。它的官方定位是一句话Utility project to generate automatically the swagger definition from the source code.也就是说它不参与运行时逻辑只在构建期完成一项工作扫描 Flowable REST 模块中带 Swagger/OpenAPI 注解的 Java 源码自动生成 Swagger Specification V2YAML 格式接口定义文件。这样当 REST Controller 的签名、参数、返回类型发生变化时接口文档可以由构建流程自动刷新避免文档与代码脱节。从源码结构看该工具自身不包含任何业务 Java 代码src/main下仅有资源与构建描述符其核心生成能力全部委托给 Maven 插件完成swagger-maven-plugincom.github.kongchen:swagger-maven-plugin:3.1.7负责解析源码中的注解如Api、ApiOperation、ApiParam生成 Swagger V2 文档。Flowable REST 模块的源码中大量使用此类注解例如在 modules/flowable-rest 的org.flowable.rest.service.api包下FormDataResource.java、HistoricActivityInstanceCollectionResource.java等文件都带有成批的Api*注解它们是文档生成的直接数据来源maven-assembly-plugin在package阶段将生成的target/oas目录整体打成 zip 压缩包方便分发详见下文产物打包一节。快速上手三种典型构建命令原文档给出了三条可直接复制的 Maven 命令覆盖了最常见的两种构建目标与一种自定义场景这里完整保留并补充说明1. 为 flowable-rest 构建默认mvn clean package作用为flowable-rest应用生成 Swagger 定义目标主机默认为localhost端口 8080适用场景本地开发环境直接构建默认的 Process REST API 文档说明该命令等同于显式指定-Prest-appProfilerest-app 正是默认激活的构建目标见下文 Profile 一节。2. 为 flowable-task 构建mvn clean package -Ptask-app作用切换构建目标为flowable-task应用生成的文档以flowable-task为应用名、以process-api为 API 端点前缀适用场景Flowable Task 应用任务管理应用自带一套独立挂载的 REST API需要为其单独生成接口定义。3. 为 flowable-task 指定自定义主机名mvn clean package -Ptask-app -Dswagger.host10.0.0.1:9090作用在-Ptask-app基础上通过-Dswagger.host10.0.0.1:9090覆盖文档中声明的服务器主机与端口适用场景需要把生成的 YAML 直接分发给外部客户端或 CI 环境且目标服务部署在特定 IP/端口如内网网关10.0.0.1:9090时原理-Dswagger.host以命令行系统属性的形式注入构建其值会覆盖 POM 属性${flowable.app.host}的默认值localhost:8080见 pom.xml最终反映到 YAML 的host字段中。构建原理从 Java 注解到 Swagger V2 YAML整个生成链路可以概括为四个阶段扫描swagger-maven-plugin 按locations配置的包路径如org.flowable.rest.service.api、org.flowable.dmn.rest.service.api扫描源码解析读取 Spring MVC 的RequestMapping/RestController风格注解与 Swagger 注解构建 API 元数据模型装配将元数据与 POM 中配置的info标题、版本、联系方式、schemeshttp/https、host、basePath、securityDefinitionsbasicAuth 安全认证等信息合并输出按outputFormatsyaml/outputFormats以 YAML 格式写出 Swagger V2 文件并附带 JSON 示例值jsonExampleValuestrue/jsonExampleValues。生成器在 POM 中同时声明了Process与Decision两个apiSource见 pom.xml分别对应两套 REST APIapiSource扫描位置basePath输出文件名输出目录Processorg.flowable.rest.service.api/${flowable.app.name}/service默认flowable-swagger-processtarget/oas/v2/processDecisionorg.flowable.dmn.rest.service.api/${flowable.app.name}/dmn-apiflowable-swagger-decisiontarget/oas/v2/decision两者均配置了 http/https 双协议、basicAuth基础认证安全定义以及来自src/main/resources/swagger/info.txt的描述文本。插件还额外声明了jaxb-api与固定版本的spring-web/spring-context依赖以避免 Swagger 插件自带的旧版 Spring 与项目版本冲突见 pom.xml。关键配置项与 Maven Profile 机制默认属性生成器的默认行为由 POM 顶部的properties定义见 pom.xml属性默认值含义flowable.app.hostlocalhost:8080文档中声明的服务主机与端口flowable.app.nameflowable-rest应用名称参与basePath拼接flowable.process.api.endpointserviceProcess API 的端点后缀flowable.prefixflowable-swagger输出文件名前缀swagger.generated.directorytarget/generated-swagger生成目录的备用引用路径Profilerest-app 与 task-app-Ptask-app背后的机制是 POM 中的两个 Profile见 pom.xmlProfileflowable.app.nameflowable.process.api.endpoint效果rest-appflowable-restservicebasePath 形如/flowable-rest/servicetask-appflowable-taskprocess-apibasePath 形如/flowable-task/process-api因此mvn clean package -Ptask-app -Dswagger.host10.0.0.1:9090实际等效于以flowable-task应用身份、10.0.0.1:9090主机、/flowable-task/process-api为 basePath 生成文档。命令行-D系统属性的优先级高于 POM 中同名属性这是它能覆盖flowable.app.host的原因。产物结构与打包构建完成后生成产物位于target目录下target/oas/v2/process/flowable-swagger-process.yaml target/oas/v2/decision/flowable-swagger-decision.yaml同时 maven-assembly-plugin 会根据 assembly.xml 的打包描述符id 为v2格式为 zip将整个target/oas目录压缩为 zip 归档便于一次性拷贝分发。生成结果在仓库中的落地与人工修正需要特别强调的是自动生成的 YAML 并不等于仓库中最终发布的文档。在 docs/public-api/references/swagger/README.md 中有明确的工程约定由于 Swagger V2 设计能力与 Flowable REST API 实际设计之间存在差异自动生成的文件会包含一些必须人工修正的问题仓库 docs/public-api/references 目录下维护的才是稳定版本的文档可供外部工具直接消费其中标记了因设计限制产生的说明源码中遗留的 OAS 问题一般以FIXME OASv3注释标记便于检索与跟踪docs/public-api/references/openapi/README.md 还明确警告不要把自动生成的 OpenAPI 文件直接复制粘贴进该目录OpenAPI V3 规范文件目前尚不完整。因此仓库内可见两类最终产物见 docs/public-api/references/README.mdSwagger V2如 process/flowable-swagger-process.yaml、decision/flowable-swagger-decision.yaml、cmmn/flowable-swagger-cmmn.yaml 等OpenAPI V3如 openapi/process/flowable-oas-process.yaml其头部声明了openapi: 3.0.0与http(s)://localhost:8080/flowable-rest/service的服务器地址信息。与周边文档工具链的协作flowable-oas-generator是 Flowable 公共 API 文档体系的第一环它生成的 Swagger 定义还被下游多个工具消费flowable-slate通过 generate-oas.sh 调用widdershins将 OAS 文件转换为 Markdown再用 Slate 渲染为静态 API 文档站点flowable-rest-asciidoc基于 Swagger 定义生成 Asciidoc 格式的 REST 章节见 flowable-rest-asciidoc/README.md可手动集成进用户指南flowable-swagger-codegen利用 Swagger Codegen 生成 Java、Swift、JS、Kotlin 等语言的客户端 SDK 骨架见 flowable-swagger-codegen/README.md官方建议仅作为 SDK 雏形生成后仍需按团队规范人工审查与改造。小结flowable-oas-generator以最小的代价把接口文档维护变成了构建期的一等公民三条 Maven 命令即可针对flowable-rest/flowable-task两种应用形态、任意主机地址从源码注解自动产出 Swagger V2 YAML再配合仓库中的人工修正流程与 slate/asciidoc/codegen 等下游工具最终形成完整的 Flowable 公共 API 文档体系。对需要自托管 Flowable REST 文档或二次开发客户端 SDK 的团队而言理解这条生成链路即可快速复现官方文档的完整生产过程。【免费下载链接】flowable-engineA compact and highly efficient workflow and Business Process Management (BPM) platform for developers, system admins and business users.项目地址: https://gitcode.com/GitHub_Trending/fl/flowable-engine创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考