diff --git a/src/_data/sidebars/help.yml b/src/_data/sidebars/help.yml index da04e793..b4702298 100644 --- a/src/_data/sidebars/help.yml +++ b/src/_data/sidebars/help.yml @@ -101,6 +101,8 @@ resources: link: /specification-support/extensions/ - label: Badges link: /specification-support/doc-badges/ + - label: Roles requirements + link: /specification-support/roles-requirements/ - label: Custom meta tags link: /specification-support/meta-tags/ - label: OpenAPI support diff --git a/src/_help/specification-support/extensions.md b/src/_help/specification-support/extensions.md index b97f1965..9897404a 100644 --- a/src/_help/specification-support/extensions.md +++ b/src/_help/specification-support/extensions.md @@ -41,4 +41,8 @@ This custom property lets you add custom meta tags in the `` tag of your d ## Change tags display name (`x-displayName`) -This custom property lets you change the display name of your OpenAPI tags. Find out more in our [dedicated section](/help/specification-support/openapi-support/x-display-name). \ No newline at end of file +This custom property lets you change the display name of your OpenAPI tags. Find out more in our [dedicated section](/help/specification-support/openapi-support/x-display-name). + +## Define role requirements (`x-rolesRequirements`) + +This custom property specifies which roles or permissions are required to access an endpoint. Find out more in our [dedicated section](/help/specification-support/roles-requirements). \ No newline at end of file diff --git a/src/_help/specification-support/roles-requirements.md b/src/_help/specification-support/roles-requirements.md new file mode 100644 index 00000000..f6adeda1 --- /dev/null +++ b/src/_help/specification-support/roles-requirements.md @@ -0,0 +1,44 @@ +--- +title: Role requirements +--- + +- TOC +{:toc} + +Specify which roles or permissions are required to access an API endpoint with `x-rolesRequirements`. Combined with security schemes, this extension helps your API users understand both **what authentication method** they need and **what access levels or roles** their credentials must have. + +Add the `x-rolesRequirements` property to any OpenAPI/AsyncAPI operation or OpenAPI webhook. The property accepts either a string or an array of strings. + +### Example usage + +#### Using an array of strings + +```yaml +paths: + /clusters: + post: + summary: Create a new cluster + x-rolesRequirements: + - Organization owner + - Product owner + # ... rest of operation +``` + +![Screenshot of an example API documentation on Bump.sh, with a multilines roles requirements area.](/docs/images/help/roles-requirements-multilines.png) + +#### Using a single string + +```yaml +paths: + /clusters/{id}: + get: + summary: Get cluster details + x-rolesRequirements: "Cluster privileges: read" + # ... rest of operation +``` + +![Screenshot of an example API documentation on Bump.sh, with a single line roles requirements area.](/docs/images/help/roles-requirements-single-line.png) + +### Impact on the changelog + +Roles requirements updates are not visible in the changelog. \ No newline at end of file diff --git a/src/docs/images/help/roles-requirements-multilines.png b/src/docs/images/help/roles-requirements-multilines.png new file mode 100644 index 00000000..34b3445f Binary files /dev/null and b/src/docs/images/help/roles-requirements-multilines.png differ diff --git a/src/docs/images/help/roles-requirements-single-line.png b/src/docs/images/help/roles-requirements-single-line.png new file mode 100644 index 00000000..0e9aba4b Binary files /dev/null and b/src/docs/images/help/roles-requirements-single-line.png differ