feat: Zeebe REST API Explorer (integrated approach) #3529
Merged
Conversation
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
> [email protected] prettier > prettier Usage: prettier [options] [file/dir/glob ...] By default, output is written to stdout. Stdin is read if it is piped to Prettier and no files are given. Output options: -c, --check Check if the given files are formatted, print a human-friendly summary message and paths to unformatted files (see also --list-different). -l, --list-different Print the names of files that are different from Prettier's formatting (see also --check). -w, --write Edit files in-place. (Beware!) Format options: --arrow-parens <always|avoid> Include parentheses around a sole arrow function parameter. Defaults to always. --bracket-same-line Put > of opening tags on the last line instead of on a new line. Defaults to false. --no-bracket-spacing Do not print spaces between brackets. --embedded-language-formatting <auto|off> Control how Prettier formats quoted code embedded in the file. Defaults to auto. --end-of-line <lf|crlf|cr|auto> Which end of line characters to apply. Defaults to lf. --html-whitespace-sensitivity <css|strict|ignore> How to handle whitespaces in HTML. Defaults to css. --jsx-single-quote Use single quotes in JSX. Defaults to false. --parser <flow|babel|babel-flow|babel-ts|typescript|acorn|espree|meriyah|css|less|scss|json|json5|json-stringify|graphql|markdown|mdx|vue|yaml|glimmer|html|angular|lwc> Which parser to use. --print-width <int> The line length where Prettier will try wrap. Defaults to 80. --prose-wrap <always|never|preserve> How to wrap prose. Defaults to preserve. --quote-props <as-needed|consistent|preserve> Change when properties in objects are quoted. Defaults to as-needed. --no-semi Do not print semicolons, except at the beginning of lines which may need them. --single-attribute-per-line Enforce single attribute per line in HTML, Vue and JSX. Defaults to false. --single-quote Use single quotes instead of double quotes. Defaults to false. --tab-width <int> Number of spaces per indentation level. Defaults to 2. --trailing-comma <all|es5|none> Print trailing commas wherever possible when multi-line. Defaults to all. --use-tabs Indent with tabs instead of spaces. Defaults to false. --vue-indent-script-and-style Indent script and style tags in Vue files. Defaults to false. Config options: --config <path> Path to a Prettier configuration file (.prettierrc, package.json, prettier.config.js). --no-config Do not look for a configuration file. --config-precedence <cli-override|file-override|prefer-file> Define in which order config files and CLI options should be evaluated. Defaults to cli-override. --no-editorconfig Don't take .editorconfig into account when parsing configuration. --find-config-path <path> Find and print the path to a configuration file for the given input file. --ignore-path <path> Path to a file with patterns describing files to ignore. Multiple values are accepted. Defaults to [.gitignore, .prettierignore]. --plugin <path> Add a plugin. Multiple plugins can be passed as separate `--plugin`s. Defaults to []. --with-node-modules Process files inside 'node_modules' directory. Editor options: --cursor-offset <int> Print (to stderr) where a cursor at the given position would move to after formatting. This option cannot be used with --range-start and --range-end. Defaults to -1. --range-end <int> Format code ending at a given character offset (exclusive). The range will extend forwards to the end of the selected statement. This option cannot be used with --cursor-offset. Defaults to Infinity. --range-start <int> Format code starting at a given character offset. The range will extend backwards to the start of the first line containing the selected statement. This option cannot be used with --cursor-offset. Defaults to 0. Other options: --cache Only format changed files. Cannot use with --stdin-filepath. Defaults to false. --cache-location <path> Path to the cache file. --cache-strategy <metadata|content> Strategy for the cache to use for detecting changed files. --no-color Do not colorize error messages. --no-error-on-unmatched-pattern Prevent errors when pattern is unmatched. --file-info <path> Extract the following info (as JSON) for a given file path. Reported fields: * ignored (boolean) - true if file path is filtered by --ignore-path * inferredParser (string | null) - name of parser inferred from file path -h, --help <flag> Show CLI usage, or details about the given flag. Example: --help write -u, --ignore-unknown Ignore unknown files. --insert-pragma Insert @Format pragma into file's first docblock comment. Defaults to false. --log-level <silent|error|warn|log|debug> What level of logs to report. Defaults to log. --require-pragma Require either '@prettier' or '@Format' to be present in the file's first docblock comment in order for it to be formatted. Defaults to false. --stdin-filepath <path> Path to the file to pretend that stdin comes from. --support-info Print support information as JSON. -v, --version Print Prettier version.
…ier'ed, but they do
This reverts commit 6ebe63b.
…Explorer" This reverts commit 4d7eec8.
|
👋 🤖 🤔 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.4/.
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. |
pepopowitz
added
kind/enhancement
pepopowitz
commented
Mar 26, 2024
api/zeebe/post-generate.sh
Outdated
There was a problem hiding this comment.
This shell script is run during the package.json script that generates the docs.
| "Zeebe API (REST)": [ | ||
| "apis-tools/zeebe-api-rest/zeebe-api-rest-overview", | ||
| { | ||
| Specifications: require("./specifications/sidebar.js"), |
There was a problem hiding this comment.
I opted to put the generated docs inside a section named "Specifications". Among other reasons, this allows me to avoid dealing with a confusing conflict between the "Overview" doc, which we manage manually and will eventually contain more useful information for getting started with the API, and the generated "Introduction" doc, which is less useful but any manual changes to it would easily be overwritten during generation.
Comment on lines
11
to
13
| :::note | ||
| Ensure you authenticate before accessing the Zeebe REST API. | ||
| ::: |
There was a problem hiding this comment.
This is lacking any details on how to authenticate! I'll follow up in #3277 about who will write this documentation.
There was a problem hiding this comment.
I will add this. We'll link to the same page as we did for the gRPC stuff, as it won't greatly differ.
There was a problem hiding this comment.
I missed this message @npepinpe! My apologies for doing something that you said you were going to do 😅
Comment on lines
+417
to
+418
| docLayoutComponent: "@theme/DocPage", | ||
| docItemComponent: "@theme/ApiItem", |
There was a problem hiding this comment.
These overrides are applied to the entire main docs instance, so that API Explorer pages can render properly. I have not found any regressions caused by overriding these for other pages, but we should keep an eye out for that happening.
| "<!-- I don't know why these generated docs need to be prettier'ed twice but they do -->": "", | ||
| "api:generate:operate": "docusaurus clean-api-docs operate -p api-operate-openapi && docusaurus gen-api-docs operate -p api-operate-openapi && prettier --write api/operate/docs/ && prettier --write api/operate/docs/", | ||
| "api:generate:tasklist": "docusaurus clean-api-docs tasklist -p api-tasklist-openapi && docusaurus gen-api-docs tasklist -p api-tasklist-openapi && prettier --write api/tasklist/docs/ && prettier --write api/operate/docs/", | ||
| "api:generate:zeebe": "docusaurus clean-api-docs zeebe -p api-zeebe-openapi && docusaurus gen-api-docs zeebe -p api-zeebe-openapi && bash ./api/zeebe/post-generate.sh && prettier --write docs/apis-tools/zeebe-api-rest/specifications && prettier --write docs/apis-tools/zeebe-api-rest/specifications" |
There was a problem hiding this comment.
This script is kind of lengthy, but it does all the things that need to happen for re-generation.
It relies on bash to run a shell script. Is this inappropriate? Does this need to be rewritten to be more cross-platform?
pepopowitz
requested review from
christinaausley,
akeller,
tmetzke and
koevskinikola
npepinpe
previously approved these changes
Mar 27, 2024
|
Body has been updated to include information about an Authentication page, which can be seen here in the preview site, or here for the commit itself. |
pepopowitz
commented
Mar 28, 2024
| For example, send a request using _curl_: | ||
|
|
||
| ```shell | ||
| curl -X POST -H -H :accept: application/json" -H "Authorization: Bearer <TOKEN>" -d '' http://localhost:8080/v1/topology |
There was a problem hiding this comment.
Note that the endpoint here is a Zeebe REST endpoint, not a Tasklist endpoint (where I pulled this doc originally from).
| | ------------------------ | ----------------------------------------------- | ------------------ | | ||
| | client id | Name of your registered client | - | | ||
| | client secret | Password for your registered client | - | | ||
| | audience | Permission name; if not given use default value | `zeebe.camunda.io` | |
There was a problem hiding this comment.
Is this audience correct?
There was a problem hiding this comment.
I have to write the docs for the REST API anyway this week, so I'll go over it and add any minor touch ups required.
| "expires_in": 86400, | ||
| "token_type": "Bearer" | ||
| } | ||
| ``` |
There was a problem hiding this comment.
The Tasklist Auth doc has a section on self-managed authentication, but it just links to a self-managed doc. I did not find a similar doc for Zeebe so I removed that section here.
christinaausley
approved these changes
Mar 29, 2024
|
This has gone pretty quiet over the past couple days, I'm merging to get it out there. If people have feedback after the merge, I'm happy to address it in follow-up PRs. |
Merged
13 tasks
github-merge-queue bot
pushed a commit
to camunda/camunda
that referenced
this pull request
Mar 29, 2024
…perience (#17201) ## Description A few minor modifications to the REST OpenAPI spec, to align with the changes I made in camunda/camunda-docs#3529. These changes were made to improve the docs.camunda.io browsing experience. See [here](https://stage.docs.camunda.io/docs/next/apis-tools/zeebe-api-rest/specifications/zeebe-rest-api/) to see the changes applied on the docs side. 1. Modifies endpoint names to (a) remove periods, and (b) shorten the language. This align this API's left-nav with other APIs in docs.camunda.io. 2. Adds tags to each endpoint. This allows the docs.camunda.io navigation to be grouped by resource. 3. Adds a `bearerAuth` security scheme. This instructs the docs.camunda.io documentation to specify that authentication is required. If any of these changes feel inappropriate to make here at the source, let me know, and I can update the PR with only the changes you wish to include. <!-- Cut-off marker _All lines under and including the cut-off marker will be removed from the merge commit message_ ## Definition of Ready Please check the items that apply, before requesting a review. You can find more details about these items in our wiki page about [Pull Requests and Code Reviews](https://github.com/camunda/zeebe/wiki/Pull-Requests-and-Code-Reviews). * [x] I've reviewed my own code * [x] I've written a clear changelist description * [x] I've narrowly scoped my changes * [x] I've separated structural from behavioural changes --> ## Definition of Done <!-- Please check the items that apply, before merging or (if possible) before requesting a review. --> _Not all items need to be done depending on the issue and the pull request._ Code changes: * [ ] The changes are backwards compatibility with previous versions * [ ] If it fixes a bug then PRs are created to [backport](https://github.com/camunda/zeebe/compare/stable/0.24...main?expand=1&template=backport_template.md&title=[Backport%200.24]) the fix to the last two minor versions. You can trigger a backport by assigning labels (e.g. `backport stable/1.3`) to the PR, in case that fails you need to create backports manually. Testing: * [ ] There are unit/integration tests that verify all acceptance criterias of the issue * [ ] New tests are written to ensure backwards compatibility with further versions * [ ] The behavior is tested manually * [ ] The change has been verified by a QA run * [ ] The impact of the changes is verified by a benchmark Documentation: * [x] The documentation is updated (e.g. BPMN reference, configuration, examples, get-started guides, etc.) * [ ] If the PR changes how BPMN processes are validated (e.g. support new BPMN element) then the Camunda modeling team should be informed to adjust the BPMN linting. Other teams: If the change impacts another team an issue has been created for this team, explaining what they need to do to support this change. - [ ] [Tasklist](https://github.com/camunda/tasklist/issues) - [ ] [Web Modeler](https://github.com/camunda/web-modeler/issues) - [ ] [Desktop Modeler](https://github.com/camunda/camunda-modeler/issues) - [ ] [Optimize](https://github.com/camunda/camunda-optimize/issues) Please refer to our [review guidelines](https://github.com/camunda/zeebe/wiki/Pull-Requests-and-Code-Reviews#code-review-guidelines).
theburi
pushed a commit
that referenced
this pull request
Apr 3, 2024
* feat: configure zeebe api explorer * feat: generate zeebe rest api docs * feat: show correct version for Zeebe API Explorer * chore: pass-through script to prettier so i can call it like > [email protected] prettier > prettier Usage: prettier [options] [file/dir/glob ...] By default, output is written to stdout. Stdin is read if it is piped to Prettier and no files are given. Output options: -c, --check Check if the given files are formatted, print a human-friendly summary message and paths to unformatted files (see also --list-different). -l, --list-different Print the names of files that are different from Prettier's formatting (see also --check). -w, --write Edit files in-place. (Beware!) Format options: --arrow-parens <always|avoid> Include parentheses around a sole arrow function parameter. Defaults to always. --bracket-same-line Put > of opening tags on the last line instead of on a new line. Defaults to false. --no-bracket-spacing Do not print spaces between brackets. --embedded-language-formatting <auto|off> Control how Prettier formats quoted code embedded in the file. Defaults to auto. --end-of-line <lf|crlf|cr|auto> Which end of line characters to apply. Defaults to lf. --html-whitespace-sensitivity <css|strict|ignore> How to handle whitespaces in HTML. Defaults to css. --jsx-single-quote Use single quotes in JSX. Defaults to false. --parser <flow|babel|babel-flow|babel-ts|typescript|acorn|espree|meriyah|css|less|scss|json|json5|json-stringify|graphql|markdown|mdx|vue|yaml|glimmer|html|angular|lwc> Which parser to use. --print-width <int> The line length where Prettier will try wrap. Defaults to 80. --prose-wrap <always|never|preserve> How to wrap prose. Defaults to preserve. --quote-props <as-needed|consistent|preserve> Change when properties in objects are quoted. Defaults to as-needed. --no-semi Do not print semicolons, except at the beginning of lines which may need them. --single-attribute-per-line Enforce single attribute per line in HTML, Vue and JSX. Defaults to false. --single-quote Use single quotes instead of double quotes. Defaults to false. --tab-width <int> Number of spaces per indentation level. Defaults to 2. --trailing-comma <all|es5|none> Print trailing commas wherever possible when multi-line. Defaults to all. --use-tabs Indent with tabs instead of spaces. Defaults to false. --vue-indent-script-and-style Indent script and style tags in Vue files. Defaults to false. Config options: --config <path> Path to a Prettier configuration file (.prettierrc, package.json, prettier.config.js). --no-config Do not look for a configuration file. --config-precedence <cli-override|file-override|prefer-file> Define in which order config files and CLI options should be evaluated. Defaults to cli-override. --no-editorconfig Don't take .editorconfig into account when parsing configuration. --find-config-path <path> Find and print the path to a configuration file for the given input file. --ignore-path <path> Path to a file with patterns describing files to ignore. Multiple values are accepted. Defaults to [.gitignore, .prettierignore]. --plugin <path> Add a plugin. Multiple plugins can be passed as separate `--plugin`s. Defaults to []. --with-node-modules Process files inside 'node_modules' directory. Editor options: --cursor-offset <int> Print (to stderr) where a cursor at the given position would move to after formatting. This option cannot be used with --range-start and --range-end. Defaults to -1. --range-end <int> Format code ending at a given character offset (exclusive). The range will extend forwards to the end of the selected statement. This option cannot be used with --cursor-offset. Defaults to Infinity. --range-start <int> Format code starting at a given character offset. The range will extend backwards to the start of the first line containing the selected statement. This option cannot be used with --cursor-offset. Defaults to 0. Other options: --cache Only format changed files. Cannot use with --stdin-filepath. Defaults to false. --cache-location <path> Path to the cache file. --cache-strategy <metadata|content> Strategy for the cache to use for detecting changed files. --no-color Do not colorize error messages. --no-error-on-unmatched-pattern Prevent errors when pattern is unmatched. --file-info <path> Extract the following info (as JSON) for a given file path. Reported fields: * ignored (boolean) - true if file path is filtered by --ignore-path * inferredParser (string | null) - name of parser inferred from file path -h, --help <flag> Show CLI usage, or details about the given flag. Example: --help write -u, --ignore-unknown Ignore unknown files. --insert-pragma Insert @Format pragma into file's first docblock comment. Defaults to false. --log-level <silent|error|warn|log|debug> What level of logs to report. Defaults to log. --require-pragma Require either '@prettier' or '@Format' to be present in the file's first docblock comment in order for it to be formatted. Defaults to false. --stdin-filepath <path> Path to the file to pretend that stdin comes from. --support-info Print support information as JSON. -v, --version Print Prettier version. * refactor: align endpoint descriptions with other explorers * oops: revert this https change that I keep making for some reason * fix: override display of additionalProperties in schemas * confused: I don't know why the generated docs need to be double-prettier'ed, but they do * chore: update OpenAPI spec * fix: adjust Zeebe API version based on spec * feat: display an 'unreleased' banner at the top of the Zeebe Explorer * feat: migrate zeebe rest api docs into main docs instance * Revert "feat: show correct version for Zeebe API Explorer" This reverts commit 6ebe63b. * Revert "feat: display an 'unreleased' banner at the top of the Zeebe Explorer" This reverts commit 4d7eec8. * refactor: zeebe rest overview * docs: describe auth for zeebe rest api
theburi
pushed a commit
that referenced
this pull request
Jun 5, 2024
* feat: configure zeebe api explorer * feat: generate zeebe rest api docs * feat: show correct version for Zeebe API Explorer * chore: pass-through script to prettier so i can call it like > [email protected] prettier > prettier Usage: prettier [options] [file/dir/glob ...] By default, output is written to stdout. Stdin is read if it is piped to Prettier and no files are given. Output options: -c, --check Check if the given files are formatted, print a human-friendly summary message and paths to unformatted files (see also --list-different). -l, --list-different Print the names of files that are different from Prettier's formatting (see also --check). -w, --write Edit files in-place. (Beware!) Format options: --arrow-parens <always|avoid> Include parentheses around a sole arrow function parameter. Defaults to always. --bracket-same-line Put > of opening tags on the last line instead of on a new line. Defaults to false. --no-bracket-spacing Do not print spaces between brackets. --embedded-language-formatting <auto|off> Control how Prettier formats quoted code embedded in the file. Defaults to auto. --end-of-line <lf|crlf|cr|auto> Which end of line characters to apply. Defaults to lf. --html-whitespace-sensitivity <css|strict|ignore> How to handle whitespaces in HTML. Defaults to css. --jsx-single-quote Use single quotes in JSX. Defaults to false. --parser <flow|babel|babel-flow|babel-ts|typescript|acorn|espree|meriyah|css|less|scss|json|json5|json-stringify|graphql|markdown|mdx|vue|yaml|glimmer|html|angular|lwc> Which parser to use. --print-width <int> The line length where Prettier will try wrap. Defaults to 80. --prose-wrap <always|never|preserve> How to wrap prose. Defaults to preserve. --quote-props <as-needed|consistent|preserve> Change when properties in objects are quoted. Defaults to as-needed. --no-semi Do not print semicolons, except at the beginning of lines which may need them. --single-attribute-per-line Enforce single attribute per line in HTML, Vue and JSX. Defaults to false. --single-quote Use single quotes instead of double quotes. Defaults to false. --tab-width <int> Number of spaces per indentation level. Defaults to 2. --trailing-comma <all|es5|none> Print trailing commas wherever possible when multi-line. Defaults to all. --use-tabs Indent with tabs instead of spaces. Defaults to false. --vue-indent-script-and-style Indent script and style tags in Vue files. Defaults to false. Config options: --config <path> Path to a Prettier configuration file (.prettierrc, package.json, prettier.config.js). --no-config Do not look for a configuration file. --config-precedence <cli-override|file-override|prefer-file> Define in which order config files and CLI options should be evaluated. Defaults to cli-override. --no-editorconfig Don't take .editorconfig into account when parsing configuration. --find-config-path <path> Find and print the path to a configuration file for the given input file. --ignore-path <path> Path to a file with patterns describing files to ignore. Multiple values are accepted. Defaults to [.gitignore, .prettierignore]. --plugin <path> Add a plugin. Multiple plugins can be passed as separate `--plugin`s. Defaults to []. --with-node-modules Process files inside 'node_modules' directory. Editor options: --cursor-offset <int> Print (to stderr) where a cursor at the given position would move to after formatting. This option cannot be used with --range-start and --range-end. Defaults to -1. --range-end <int> Format code ending at a given character offset (exclusive). The range will extend forwards to the end of the selected statement. This option cannot be used with --cursor-offset. Defaults to Infinity. --range-start <int> Format code starting at a given character offset. The range will extend backwards to the start of the first line containing the selected statement. This option cannot be used with --cursor-offset. Defaults to 0. Other options: --cache Only format changed files. Cannot use with --stdin-filepath. Defaults to false. --cache-location <path> Path to the cache file. --cache-strategy <metadata|content> Strategy for the cache to use for detecting changed files. --no-color Do not colorize error messages. --no-error-on-unmatched-pattern Prevent errors when pattern is unmatched. --file-info <path> Extract the following info (as JSON) for a given file path. Reported fields: * ignored (boolean) - true if file path is filtered by --ignore-path * inferredParser (string | null) - name of parser inferred from file path -h, --help <flag> Show CLI usage, or details about the given flag. Example: --help write -u, --ignore-unknown Ignore unknown files. --insert-pragma Insert @Format pragma into file's first docblock comment. Defaults to false. --log-level <silent|error|warn|log|debug> What level of logs to report. Defaults to log. --require-pragma Require either '@prettier' or '@Format' to be present in the file's first docblock comment in order for it to be formatted. Defaults to false. --stdin-filepath <path> Path to the file to pretend that stdin comes from. --support-info Print support information as JSON. -v, --version Print Prettier version. * refactor: align endpoint descriptions with other explorers * oops: revert this https change that I keep making for some reason * fix: override display of additionalProperties in schemas * confused: I don't know why the generated docs need to be double-prettier'ed, but they do * chore: update OpenAPI spec * fix: adjust Zeebe API version based on spec * feat: display an 'unreleased' banner at the top of the Zeebe Explorer * feat: migrate zeebe rest api docs into main docs instance * Revert "feat: show correct version for Zeebe API Explorer" This reverts commit 6ebe63b. * Revert "feat: display an 'unreleased' banner at the top of the Zeebe Explorer" This reverts commit 4d7eec8. * refactor: zeebe rest overview * docs: describe auth for zeebe rest api
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
Description
Replaces #3487; resolves #3421.
Introduces a Zeebe REST API Explorer, in a more integrated approach than #3487.
What it looks like:
Preview site
https://loquacious-pika-a05ac2.netlify.app/docs/next/apis-tools/zeebe-api-rest/zeebe-api-rest-overview/
What's included
What's not included yet and blocks this PR from merging
What's not included but does not block this PR from merging
When should this change go live?
holdlabel or convert to draft PR)?PR Checklist
/versioned_docsdirectory, or they are not for an already released version./docsdirectory (aka/next/), or they are not for future versions.