一个灵活的工作流程和流程自动化框架 它的核心是在 Java 虚拟机中运行的原生 BPMN 2.0 流程引擎

REST API - OpenAPI documentation generation ======== This project generates a single openapi.json containing the OpeanAPI documentation of the Engine Rest API. Aligned with OpeanAPI specification version [3.0.2](https://github.com/OAI/OpenAPI-Specification/blob/3.0.2/versions/3.0.2.md). # Table of Contents 1. [Build and phases](#build-and-phases) 2. [Contribution](#contribution) + [main.ftl](#mainftl) + [utils](#utils) + [models](#models) + [paths](#paths) + [commons](#commons) + [sorting](#sorting) + [pagination](#pagination) + [reuse](#reuse) + [descriptions](#descriptions) + [formats](#formats) + [nullable](#nullable) + [examples](#examples) 3. [Reviews](#reviews) ## Build and phases To build the artifact run: `mvn clean install` The build contains: * Generation of a formatted openapi.json file by parsing the [templates](./src/main/templates) * Validation of the generated file against [schema.json](./src/main/openapi/schema.json) * Generation of a java client from the openapi.json file * Run of smoke tests against that client (the tests use [WireMock](http://wiremock.org/docs/)) ## Contribution NOTE: Please follow the next step to get familiar with the structure and the instructions that follow. For the generation of the documentation, we use the [Freemarker](https://freemarker.apache.org/docs/index.html) templating language. The structure of the template is: ``` +--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 ``` ### main.ftl The `main.ftl` contains the general information of the OpenAPI doc: * OpenAPI spec version * info * externalDocs * servers (default and named) * tags (each resource has a tag) * Sub-resources should have the parent tag as prefix (e.g. `Task` and `Task Attachment`) * wrap up of paths and components By parsing this file end .json file is generated. ### utils Contains all of the [macros](https://freemarker.apache.org/docs/ref_directive_macro.html) used in paths and models: * `parameter` (used in paths) * `property` (used in paths and models) * `requestBody` (used in paths) * `response` (used in paths) Try to get familiar with them as they are heavily used in the templates. Keep in mind that in some situations, it is fine not to use them, if the endpoint/dto is too complex, for example. Feel free to add missing parameters to the macros, however, do not forget to reflect your changes to all usages of the macros. Some parameters are required (`name` and `description` in most of the cases), and some need to be provided if necessary (nice to have - `minimum`,`defaultValue`, `deprecated`). ### models This folder contains all of the DTOs used in the request and response bodies. Instructions: * use the name and package structure of the Rest DTOs when possible ([org.camunda.bpm.engine.rest.dto.ExceptionDto.java](https://github.com/camunda/camunda-bpm-platform/blob/master/engine-rest/engine-rest/src/main/java/org/camunda/bpm/engine/rest/dto/ExceptionDto.java) --> [org/camunda/bpm/engine/rest/dto/ExceptionDto.ftl](https://github.com/camunda/camunda-bpm-platform/blob/master/engine-rest/engine-rest-openapi/src/main/templates/models/org/camunda/bpm/engine/rest/dto/ExceptionDto.ftl)) Keep the properties of OpenAPI doc as close as possible to the Java DTOs and add explicit description whenever a property is not applicable to a certain endpoint (e.g. [PUT /process-instance/suspended](https://github.com/camunda/camunda-bpm-platform/blob/master/engine-rest/engine-rest-openapi/src/main/templates/paths/process-instance/suspended/put.ftl)) * the definitions of the models are resolved automatically via the folder structure. The `/models` directory should contain only the models that are used in the documentation, any additional files (macros and reusable files) should go to [commons](#commons), do not create empty folders. The models are ordered lexicographically. * use the [utils](#utils) from the previous section when possible. * use the `dto` macro to define a DTO * in case of a DTO hierarchy (`TriggerVariableValueDto extends VariableValueDto`), the `dto` macro provides an `extends` attribute that makes use of the `allOf` OpenAPI syntax - [example](https://github.com/camunda/camunda-bpm-platform/blob/392d98b61e5e0eff3e1dad0ee15a5ad986e0d93c/engine-rest/engine-rest-openapi/src/main/templates/models/org/camunda/bpm/engine/rest/dto/runtime/TriggerVariableValueDto.ftl#L2-L19). * the `property` macros should be nested inside the `dto` macro * in case the response can be two DTOs depending on request parameter (example - [message correlation](https://docs.camunda.org/manual/develop/reference/rest/message/post-message/#result) and responses `MessageCorrelationResultDto` or `MessageCorrelationResultWithVariableDto` (extending `MessageCorrelationResultDto`)), please use the DTO for the response that contains all of the properties (in the correlation case - `MessageCorrelationResultWithVariableDto`) even some are not applicable for all of the responses, and make sure to document which properties are not applicable in which use cases. (In some use cases `oneOf` approach might be applicable together with `discrimitator` ([spec](https://github.com/OAI/OpenAPI-Specification/blob/3.0.2/versions/3.0.2.md#discriminator-object)), please test this additionally as the clients might have problems to be generated in this approach.) * for the `property` macros DO NOT forget to put `last = true` param for the last property, that will take care for the commas in the json file. * the DTOs that have sorting or pagination properties should use the [common templates](#commons). ### paths Contains the endpoints definitions of the Rest API. Instructions: * each resource has its own folder under /paths (e.g. `/process-instance`, `/deployment`) * the path of the endpoint is resolved to a folder structure (e.g. get process instance count `GET /process-instance/count` goes to `/paths/process-instance/count`). NOTE: The endpoints' paths are automatically resolved from the folder structure, please keep the file structure of `/paths` clean, without any additional files, different than the endpoint definitions (for example the reusable templates should go in [commons](#commons), do not create empty folders and so on). The endpoints' paths are ordered lexicographically. * the dynamic endpoints should be structured with brakes like `process-instance/{id}/variables/{varName}/data`, then the path parameters (`id` and `varName`) should always be included in the endpoint definition and marked as `required`. * endpoints that are almost similar but have a different paths (e.g. [Get Activity Instance Statistics](https://docs.camunda.org/manual/7.12/reference/rest/process-definition/get-activity-statistics/)) needs to be separated in different files. A unique `operationId` should be assigned to each of them. You can consider adding the common parts of the endpoints in [lib/commons](#commons). * the name of the method's request (GET, POST, PUT, DELETE, OPTIONS) is the name of the template file (get.ftl, post.frl, etc.). * each endpoint definition has a unique `operationId` that will be used for the generation of clients. * for `async` endpoints make sure to add `Operation` suffix to prevent collisions in generated C# clients, e.g. `setExternalTaskRetriesAsync` -> `setExt