feat: temporarily inject examples for mutually-exclusive request types in c8 api docs #4352
Conversation
pepopowitz
added
the
dx
|
👋 🤖 🤔 Hello! Did you make your changes in all the right places? These files were changed only in docs/. You might want to duplicate these changes in versioned_docs/version-8.5/.
You may have done this intentionally, but we wanted to point it out in case you didn't. You can read more about the versioning within our docs in our documentation guidelines. |
| @@ -4,7 +4,18 @@ const outputDir = "docs/apis-tools/camunda-api-rest/specifications"; | |||
| const specFile = "api/camunda/camunda-openapi.yaml"; | |||
|
|
|||
| function preGenerateDocs() { | |||
| hackChangesetDescription(); | |||
There was a problem hiding this comment.
This description hack is no longer needed!
| function temporarilyAddCreateProcessInstanceExamples() { | ||
| // This is a temporary hack, to add example requests to the `Create Process Instance` endpoint. | ||
| // After the upcoming release, this will be incorporated into the source spec, but the source spec is currently frozen. | ||
| return { | ||
| from: /\$ref: "#\/components\/schemas\/CreateProcessInstanceRequest"\n responses:/m, | ||
| to: `$ref: "#/components/schemas/CreateProcessInstanceRequest" | ||
| examples: | ||
| "By process decision key": | ||
| summary: "Create a process instance by processDefinitionKey." | ||
| value: | ||
| processDefinitionKey: 12345 | ||
| variables: {} | ||
| "By BPMN process ID": | ||
| summary: "Create a process instance by bpmnProcessID and version." | ||
| value: | ||
| bpmnProcessId: "1234-5678" | ||
| version: 1 | ||
| variables: {} | ||
| responses:`, | ||
| }; | ||
| } |
There was a problem hiding this comment.
I'll backport the changes into the release branch. This shouldn't be necessary then, I guess?
There was a problem hiding this comment.
Done with camunda/camunda#22715
There was a problem hiding this comment.
Great examples, thanks a lot, @pepopowitz 🦕
The hacks for the examples can be removed, I think. I'll add the source changes to the release branch as well.
Edit: examples integrated in the source, also on release branch (with camunda/camunda#22715)
Nice, thanks @tmetzke!!! I didn't expect that this would be backport-worthy, and I thought I'd have to wait until the freeze thawed. Closing!!! I'll address the removal of |
Description
Follow-up to #4308 (comment).
Following this PR, I'll open one at the camunda/camunda repo, to add these examples at the source. It won't be merged until after the release though, due to the current code freeze. Thus, this temporary hack, so that we don't have to keep modifying the spec when generating the docs for now.
What the added examples look like
Create process instance endpoint
Evaluate decision endpoint
When should this change go live?
holdlabel or convert to draft PR)PR Checklist
/versioned_docsdirectory./docsdirectory (aka/next/).My changes require an Engineering review, and I've assigned the Engineering DRI or delegate.
My changes require a technical writer review, and I've assigned @camunda/tech-writers as a reviewer.
My changes require a docs infrastructure review.