ARTICLE DETAIL

资讯详情

深耕网站建设与运营推广的一线实战洞察。

Flowable 公共 REST API 参考文档导读:Swagger V2 / OpenAPI V3 规范文件全解析

Flowable 公共 REST API 参考文档导读:Swagger V2 / OpenAPI V3 规范文件全解析 Flowable 公共 REST API 参考文档导读Swagger V2 / OpenAPI V3 规范文件全解析【免费下载链接】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本文以 docs/public-api/references/README.md 为骨架系统讲解 Flowable 公共 REST API 的规范文件体系四大 API 分组Process / Decision / Form / Content、Swagger 2.0 与 OpenAPI 3.0 双版本规范的组织方式、各 YAML 文件的仓库位置与使用方法并深入仓库配套工具链OAS 生成器、Swagger UI、Slate、Codegen 等帮助你快速定位规范、校验语法并生成客户端 SDK 或交互式 API 文档。一、Flowable 公共 REST API 概述Flowable 提供了一套面向引擎能力的公共 REST API。根据 docs/public-api/README.md 的说明这套 API 当前划分为4 组分别面向不同的引擎能力API 分组面向的引擎能力典型使用场景Process API提供对 Flowable 绝大多数服务的访问流程引擎部署 BPMN 流程、启动/操作流程实例、查询任务、管理历史数据Decision API提供对 Flowable DMN 决策引擎的访问部署决策表、执行决策规则、查询历史决策执行记录Form API提供对 Flowable 表单引擎的访问获取/提交任务表单数据Content API提供对 Flowable 内容服务的访问内容/附件相关 REST 能力注意在仓库的 references 目录下Swagger V2 与 OpenAPI V3 目录中还额外包含app、cmmn、eventregistry等规范文件见 references/swagger/README.md 所在目录的实际文件清单分别覆盖 App 引擎、CMMN 案例引擎与事件注册表说明 Flowable 的 REST API 覆盖了 BPMN、CMMN、DMN、表单、内容、事件注册等多引擎体系开发者可按需选取。二、规范文件的组织与位置本仓库在docs/public-api/references/下按规范版本 → 引擎分组两层组织 YAML 文件docs/public-api/references/ ├── openapi/ # OpenAPI Specification V3 │ ├── decision/flowable-oas-decision.yaml │ ├── process/flowable-oas-process.yaml │ └── README.md # V3 规范的注意事项 └── swagger/ # Swagger Specification V2 ├── app/flowable-swagger-app.yaml ├── cmmn/flowable-swagger-cmmn.yaml ├── decision/flowable-swagger-decision.yaml ├── eventregistry/flowable-swagger-eventregistry.yaml ├── process/flowable-swagger-process.yaml └── README.md # V2 规范的注意事项原 references/README.md 中列出的两类规范文件对应关系如下Swagger Specification V2可在线语法校验API 名称仓库相对路径Process APIswagger/process/flowable-swagger-process.yamlForm APIswagger/form/flowable-swagger-form.yamlDecision APIswagger/decision/flowable-swagger-decision.yamlContent APIswagger/content/flowable-swagger-content.yamlOpenAPI Specification V3API 名称仓库相对路径Process APIopenapi/process/flowable-oas-process.yamlForm APIopenapi/form/flowable-oas-form.yamlDecision APIopenapi/decision/flowable-oas-decision.yamlContent APIopenapi/content/flowable-oas-content.yaml说明form、content分组在当前仓库快照中位于swagger/与openapi/的目录清单之外实际发布版本中以flowable-swagger-form.yaml、flowable-swagger-content.yaml等命名存在于 references 体系内此处路径以原文档为准使用前请以实际发布产物核对。三、为什么需要 OpenAPI 规范原文档明确指出OpenAPI 是描述 REST API 的标准规范它具备以下特点厂商中立Vendor Neutral不绑定任何特定实现或云厂商有官方组织背书由 OpenAPI Initiative 维护其成员包括 Google、Microsoft、IBM、Atlassian 等大量软件公司机器可读JSON / YAML 格式描述端点、参数、请求体、响应结构与鉴权方式可供代码生成器、API 网关、文档工具直接消费。对 Flowable 而言规范文件的价值体现在生成客户端 SDK通过 Swagger Codegen / OpenAPI Generator 直接从 YAML 生成 Java、Python、TypeScript 等语言的客户端生成交互式文档将规范文件导入 Swagger UI 或基于 Slate 生成静态 API 站点自动测试与契约校验作为 REST 契约供接口测试工具如 Postman、ReadyAPI与 CI 流水线做契约测试语法自检Swagger V2 文件可配合在线 validator 校验语法正确性详见第四节。四、Swagger 2.0 规范文件解析以 flowable-swagger-process.yaml 为例该文件在仓库中约 1 万行其结构包括4.1 头部元信息infoswagger: 2.0 info: description: # flowable ... a compact and highly efficient workflow and BPM platform ... version: v1 title: Flowable REST API contact: name: Flowable url: http://www.flowable.org/ license: name: Apache 2.0 basePath: /flowable-rest/service schemes: - http - httpsbasePath: /flowable-rest/serviceProcess REST API 的公共访问前缀部署到 Tomcat 等 Servlet 容器后即通过该路径访问schemes同时声明http与https配合官方Basic Auth 建议与 HTTPS 结合使用的推荐见 ch14-REST.md。4.2 TagsAPI 资源分组Process API 规范中定义了 26 个 tag实际构成 REST 资源的分组目录Batch parts / Batches / Database tables / Deployment / Engine / Event subscriptions / Executions / Forms / Groups / Historic Task Log Entries / History / History Process / History Task / Jobs / Models / Process Definitions / Process Instance Identity Links / Process Instance Variables / Process Instances / Query / Runtime / Task Attachments / Task Comments / Task Identity Links / Task Variables / Tasks / Users这些 tag 与 REST 端点一一对应例如Deployment→ 流程部署的上传、列表、删除Process Definitions→ 流程定义查询与操作Tasks/Task Variables→ 任务及其变量管理History/Historic Activity Instances→ 历史数据查询。4.3 paths端点定义示例paths: /form/form-data: get: tags: - Forms summary: Get form data operationId: getFormData produces: - application/json parameters: - name: taskId in: query required: false type: string - name: processDefinitionId in: query required: false type: string responses: 200: description: Indicates that form data could be queried. schema: $ref: #/definitions/FormDataResponse 404: description: Indicates that form data could not be found. security: - basicAuth: [] post: summary: Submit task form data operationId: submitForm responses: 200: { ... } 204: description: If TaskId has been provided, ... Returns empty 400: description: Indicates an parameter was passed in the wrong format. ...要点GET端点通过 query 参数如taskId、processDefinitionId获取表单数据返回FormDataResponsePOST端点提交任务表单成功时若只提交任务无processDefinitionId返回204 No Content空响应体若同时启动流程则返回200与ProcessInstanceResponse每个端点都声明security: basicAuth对应 REST API 默认的 HTTP Basic 认证。4.4 语法校验原文档为 V2 规范提供了Swagger 在线校验机制可通过online.swagger.io/validator校验 YAML 是否符合 Swagger 2.0 语法例如 Process API 的校验 URL 形式为http://online.swagger.io/validator?url规范文件的可访问 URL在仓库中原文档通过引用外部校验服务展示校验结果徽标。由于规范文件位于只读仓库建议将 YAML 发布到可访问的静态地址后再使用上述 URL 模板进行在线校验也可以使用本地工具如swagger-cli validate、OpenAPI Generator 的 validator做离线校验。五、OpenAPI 3.0 规范文件解析以 flowable-oas-process.yaml 为例仓库中约 1 万行V3 版本与 V2 的关键差异5.1 servers 与 infoopenapi: 3.0.0 servers: - url: http://localhost:8080/flowable-rest/service - url: https://localhost:8080/flowable-rest/service info: version: v1 title: Flowable Process REST API ...用servers数组取代 V2 的schemes basePath默认指向localhost:8080/flowable-rest/serviceV3 将definitions迁移为components/schemas将$ref从#/definitions/...改为#/components/schemas/...。5.2 端点与请求体示例paths: /form/form-data: get: tags: [Forms] summary: Get form data operationId: getFormData parameters: - name: taskId in: query required: false schema: type: string - name: processDefinitionId in: query schema: type: string responses: 200: description: Indicates that form data could be queried. content: application/json: schema: $ref: #/components/schemas/FormDataResponse security: - basicAuth: [] post: ... requestBody: content: application/json: schema: $ref: #/components/schemas/SubmitFormRequestV3 规范中参数类型用schema.type描述响应体通过content.application/json.schema描述比 V2 更贴近实际 HTTP 语义请求体使用独立的requestBody对象与响应对象分离。5.3 DMN 规范的差异以 flowable-oas-decision.yaml 为例Decision API 的默认服务器地址为servers: - url: http://localhost:8080/flowable-rest/dmn-api其 tag 分组为DMN Rule Service / Decision Tables / Deployment / Engine / Historic Decision Executions典型的端点/dmn-history/historic-decision-executionsGET支持按id、decisionDefinitionId、deploymentId、decisionKey等条件过滤历史决策执行记录——这些过滤参数在原文档与规范中均有完整声明可直接用于实现决策审计查询。六、规范文件的生成方式与维护约束references/swagger/README.md 对规范文件的来源与维护提出了明确约束这是使用这些文件时必须了解的重要背景不要手动复制粘贴自动生成的 OAS 文件到该目录Flowable REST API 的规范文件大部分由源码中的 Swagger/OAS 注解自动生成需要人工修正由于 Swagger V2 设计与 Flowable REST API 设计的差异自动生成的文件存在一些问题必须人工修复后才可作为稳定文档版本仓库内的 YAML 代表稳定版本references目录下的文件是 API 的稳定文档版本可安全地被外部工具使用因设计约束产生的限制会在文档内部以注释形式标注源码中遗留标记在源码中OAS 相关问题一般以FIXME OASv3标注供开发者定位已知问题。references/openapi/README.md 同时提示OpenAPI V3 规范文件目前尚未完整覆盖 Flowable 公共 APIWork in progress。因此在需要完整契约时Swagger V2 文件是更成熟的选择V3 文件适合作为演进中的契约参考。七、配套工具链从规范到 SDK 与文档原 docs/public-api/README.md 提供了围绕规范文件的完整工具链均位于 docs/public-api/tools 目录下工具路径用途Flowable OpenAPI Specification Generatortools/flowable-oas-generator从源码自动生成 Swagger/OAS 定义Flowable Rest Asciidoctools/flowable-rest-asciidoc基于 OAS 文件生成 Asciidoc 文档Flowable Swagger UItools/flowable-swagger-ui构建 Swagger UI 的 WAR 包Flowable Slatetools/flowable-slate生成漂亮的静态 REST API 文档站点Flowable Swagger Codegentools/flowable-swagger-codegen生成与 Flowable REST API 交互的客户端 SDK7.1 OAS 生成器使用示例以 tools/flowable-oas-generator/README.md 为准常用命令# 为 flowable-rest 构建localhost mvn clean package # 为 flowable-task 构建localhost mvn clean package -Ptask-app # 为 flowable-task 指定特定 host 构建 mvn clean package -Ptask-app -Dswagger.host10.0.0.1:9090其中-Dswagger.host用于定制生成规范中的服务器地址便于对接不同环境的 REST 服务。7.2 快速启动 REST API 环境结合 docs/public-api/README.md 与 docker/README.md可通过 Docker 一键启动docker run -p8080:8080 flowable/flowable-rest也可将flowable-rest.war/flowable-task.war部署到 Apache Tomcat 等 Servlet 容器中。八、REST API 的部署与认证实践配套背景虽然规范文件本身不包含运行时配置但理解 REST API 的部署与认证前提能帮助你正确解读规范中的security: basicAuth。依据 ch14-REST.md默认认证所有 REST 资源默认要求拥有rest-access-api权限的有效用户如希望任何有效用户都可访问可将flowable.rest.app.authentication-mode设为any-user默认管理用户配置flowable-app.propertiesflowable.rest.app.admin.user-idrest-admin flowable.rest.app.admin.passwordtest flowable.rest.app.admin.first-nameRest flowable.rest.app.admin.last-nameAdminREST 应用启动时会自动创建或获取该用户并授予access-rest-api权限请务必在初始部署后修改默认密码若未设置user-id则不会创建任何用户或权限认证方式使用 HTTP Basic 认证需在请求头携带Authorization: Basic …官方建议Basic Auth 与 HTTPS 结合使用HTTP 方法约定GET 获取资源、POST 创建资源或执行复杂查询、PUT 更新资源或触发操作、DELETE 删除资源常用状态码200成功、201创建成功、204删除成功无响应体、401未认证、403禁止操作如删除运行中流程的任务、404资源不存在、409冲突、415不支持的媒体类型、500服务器内部错误错误响应体格式{ statusCode : 404, errorMessage : Could not find a task with id 444. }Tomcat 注意事项Tomcat 默认禁止转义斜杠%2F、%5C可能影响部署资源及其 contenteditable="false">【免费下载链接】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),仅供参考
返回列表