[TT-11185, DX-1104] Update documentation for 5.3 (Tyk Dashboard API)

[buger]

Triggered by: titpetric

Included:

Tyk Gateway: false
Tyk Dashboard: true
Tyk MDCB false
Tyk Pump false

Intended for: 5.3
Changes sourced from: release-5.3
Config info generator branch: main

Note: TT-11185, dashboard changes only (branch suffix: docs-dashboard)

JIRA: https://tyktech.atlassian.net/browse/TT-11185

[github-actions]

PR Description updated to latest commit (6e8cae8)

[netlify]

✅ PS. Pls add /docs/nightly to the end of url

Name	Link
🔨 Latest commit	2a981dd
🔍 Latest deploy log	https://app.netlify.com/sites/tyk-docs/deploys/65fd69d81aed8e0008cd1046
😎 Deploy Preview	https://deploy-preview-4176--tyk-docs.netlify.app
📱 Preview on mobile	Toggle QR Code... Use your smartphone camera to open QR code link.

---

To edit notification comments on pull requests, go to your Netlify site configuration.

[github-actions]

PR Review

(Review updated until commit 6e8cae8)

⏱️ Estimated effort to review [1-5]	2, because the PR mainly involves documentation updates and minor code changes. The documentation updates are straightforward and the code changes are not complex, but reviewing the accuracy of the documentation and ensuring the code changes align with the project's standards requires attention to detail.
🧪 Relevant tests	No
🔍 Possible issues	The PR introduces new paths and schema definitions in the Swagger documentation. It's important to ensure these paths and definitions accurately reflect the API's capabilities and constraints.
	The addition of new configuration options for Redis SSL in the dashboard configuration documentation should be carefully reviewed to ensure they are correctly explained and that the examples provided are valid.
🔒 Security concerns	No

Code feedback:

---

relevant file	tyk-docs/content/shared/dashboard-config.md
suggestion	Consider adding examples for the new Redis SSL configuration options (redis_ssl_ca_file, redis_ssl_cert_file, redis_ssl_key_file, redis_ssl_max_version, redis_ssl_min_version). Including practical examples can greatly help users understand how to correctly configure these options for their specific setups. [medium]
relevant line	ENV: TYK_DB_REDISSSLCAFILE

---

relevant file	tyk-docs/assets/others/dashboard-swagger.yml
suggestion	For the new OAS API paths and operations added, ensure that the request and response schemas are thoroughly validated against the actual API behavior. This includes checking the accuracy of the examples provided in the Swagger documentation. Inaccurate documentation can lead to confusion and misuse of the API. [important]
relevant line	/api/apis/oas/{apiID}/categories:

---

relevant file	tyk-docs/assets/others/dashboard-admin-swagger.yml
suggestion	The update to the OrganisationDocument schema definition should be closely reviewed to ensure all required fields are indeed necessary and that the schema accurately represents the data model. Consider whether all fields marked as required are mandatory for every use case. [medium]
relevant line	OrganisationDocument:

---

relevant file	tyk-docs/assets/others/dashboard-swagger.yml
suggestion	Validate the new query parameters (templateID) introduced for OAS API operations to ensure they are correctly processed by the backend and that their effects are clearly documented. Misunderstandings about the role of such parameters can lead to incorrect API usage. [medium]
relevant line	- name: templateID

---

---

✨ Review tool usage guide:

---

Overview:
The review tool scans the PR code changes, and generates a PR review. The tool can be triggered automatically every time a new PR is opened, or can be invoked manually by commenting on any PR.
When commenting, to edit configurations related to the review tool (pr_reviewer section), use the following template:

/review --pr_reviewer.some_config1=... --pr_reviewer.some_config2=...

With a configuration file, use the following template:

[pr_reviewer]
some_config1=...
some_config2=...

Utilizing extra instructions The review tool can be configured with extra instructions, which can be used to guide the model to a feedback tailored to the needs of your project. Be specific, clear, and concise in the instructions. With extra instructions, you are the prompter. Specify the relevant sub-tool, and the relevant aspects of the PR that you want to emphasize. Examples for extra instructions: [pr_reviewer] # /review # extra_instructions=""" In the 'possible issues' section, emphasize the following: - Does the code logic cover relevant edge cases? - Is the code logic clear and easy to understand? - Is the code logic efficient? ... """ Use triple quotes to write multi-line instructions. Use bullet points to make the instructions more readable.

How to enable\disable automation When you first install PR-Agent app, the default mode for the review tool is: pr_commands = ["/review", ...] meaning the review tool will run automatically on every PR, with the default configuration. Edit this field to enable/disable the tool, or to change the used configurations

Auto-labels The review tool can auto-generate two specific types of labels for a PR: a possible security issue label, that detects possible security issues (enable_review_labels_security flag) a Review effort [1-5]: x label, where x is the estimated effort to review the PR (enable_review_labels_effort flag)

Extra sub-tools The review tool provides a collection of possible feedbacks about a PR. It is recommended to review the possible options, and choose the ones relevant for your use case. Some of the feature that are disabled by default are quite useful, and should be considered for enabling. For example: require_score_review, require_soc2_ticket, and more.

Auto-approve PRs By invoking: /review auto_approve The tool will automatically approve the PR, and add a comment with the approval. To ensure safety, the auto-approval feature is disabled by default. To enable auto-approval, you need to actively set in a pre-defined configuration file the following: [pr_reviewer] enable_auto_approval = true (this specific flag cannot be set with a command line argument, only in the configuration file, committed to the repository) You can also enable auto-approval only if the PR meets certain requirements, such as that the estimated_review_effort is equal or below a certain threshold, by adjusting the flag: [pr_reviewer] maximal_review_effort = 5

More PR-Agent commands To invoke the PR-Agent, add a comment using one of the following commands: /review: Request a review of your Pull Request. /describe: Update the PR title and description based on the contents of the PR. /improve [--extended]: Suggest code improvements. Extended mode provides a higher quality feedback. /ask <QUESTION>: Ask a question about the PR. /update_changelog: Update the changelog based on the PR's contents. /add_docs 💎: Generate docstring for new components introduced in the PR. /generate_labels 💎: Generate labels for the PR based on the PR's contents. /analyze 💎: Automatically analyzes the PR, and presents changes walkthrough for each component. See the tools guide for more details. To list the possible configuration parameters, add a /config comment.

See the review usage page for a comprehensive guide on using this tool.

[github-actions]

PR Code Suggestions

	Suggestions
enhancement	Add a description for the version update.                                     Consider adding a brief description for the new version update to provide context on the changes or improvements made from the previous version. tyk-docs/assets/others/dashboard-admin-swagger.yml [4] version: 5.3.0 +# Description: [Add a brief description of the new features or improvements in version 5.3.0] Mark only essential fields as required in the OrganisationDocument schema. For the OrganisationDocument schema, consider marking fields that are not always required as optional to avoid forcing clients to provide unnecessary data. tyk-docs/assets/others/dashboard-admin-swagger.yml [1271-1286] required: - id - owner_name - - owner_slug - - cname_enabled - - cname - - apis - - sso_enabled - - developer_quota - - developer_count - - event_options - - hybrid_enabled - - ui - - org_options_meta - - open_policy - - additional_permissions + # Removed some fields from required if they are not always necessary for every organisation. Add descriptions to new properties and schemas for clarity.                   For better clarity and maintainability, consider adding descriptions to new properties and schemas introduced in the API documentation. tyk-docs/assets/others/dashboard-admin-swagger.yml [1193-1198] ApiDocument: + description: "Schema for API document detailing the human-readable name and ID." properties: api_human_name: type: string + description: "The human-readable name of the API." api_id: type: string + description: "The unique identifier of the API."
best practice	Ensure consistency in boolean value usage.                                    Ensure consistency in the use of boolean values for cname_enabled, hybrid_enabled, and other boolean fields by using true or false explicitly, as mixed usage can lead to confusion. tyk-docs/assets/others/dashboard-admin-swagger.yml [606-613] cname_enabled: true hybrid_enabled: false +# Ensure all boolean fields throughout the document follow the same explicit true/false convention.
maintainability	Use $ref to reference common property definitions in schemas.    To improve the maintainability of the schema definitions, consider using $ref to reference common property definitions instead of repeating them. tyk-docs/assets/others/dashboard-admin-swagger.yml [1193-1198] +CommonProperties: + api_human_name: + type: string + api_id: + type: string ApiDocument: properties: - api_human_name: - type: string - api_id: - type: string + $ref: '#/components/schemas/CommonProperties'

---

✨ Improve tool usage guide:

---

Overview:
The improve tool scans the PR code changes, and automatically generates suggestions for improving the PR code. The tool can be triggered automatically every time a new PR is opened, or can be invoked manually by commenting on a PR.
When commenting, to edit configurations related to the improve tool (pr_code_suggestions section), use the following template:

/improve --pr_code_suggestions.some_config1=... --pr_code_suggestions.some_config2=...

With a configuration file, use the following template:

[pr_code_suggestions]
some_config1=...
some_config2=...

Enabling\disabling automation When you first install the app, the default mode for the improve tool is: pr_commands = ["/improve --pr_code_suggestions.summarize=true", ...] meaning the improve tool will run automatically on every PR, with summarization enabled. Delete this line to disable the tool from running automatically.

Utilizing extra instructions Extra instructions are very important for the improve tool, since they enable to guide the model to suggestions that are more relevant to the specific needs of the project. Be specific, clear, and concise in the instructions. With extra instructions, you are the prompter. Specify relevant aspects that you want the model to focus on. Examples for extra instructions: [pr_code_suggestions] # /improve # extra_instructions=""" Emphasize the following aspects: - Does the code logic cover relevant edge cases? - Is the code logic clear and easy to understand? - Is the code logic efficient? ... """ Use triple quotes to write multi-line instructions. Use bullet points to make the instructions more readable.

A note on code suggestions quality While the current AI for code is getting better and better (GPT-4), it's not flawless. Not all the suggestions will be perfect, and a user should not accept all of them automatically. Suggestions are not meant to be simplistic. Instead, they aim to give deep feedback and raise questions, ideas and thoughts to the user, who can then use his judgment, experience, and understanding of the code base. Recommended to use the 'extra_instructions' field to guide the model to suggestions that are more relevant to the specific needs of the project, or use the custom suggestions 💎 tool With large PRs, best quality will be obtained by using 'improve --extended' mode.

More PR-Agent commands To invoke the PR-Agent, add a comment using one of the following commands: /review: Request a review of your Pull Request. /describe: Update the PR title and description based on the contents of the PR. /improve [--extended]: Suggest code improvements. Extended mode provides a higher quality feedback. /ask <QUESTION>: Ask a question about the PR. /update_changelog: Update the changelog based on the PR's contents. /add_docs 💎: Generate docstring for new components introduced in the PR. /generate_labels 💎: Generate labels for the PR based on the PR's contents. /analyze 💎: Automatically analyzes the PR, and presents changes walkthrough for each component. See the tools guide for more details. To list the possible configuration parameters, add a /config comment.

See the improve usage page for a more comprehensive guide on using this tool.

[titpetric]

@dcs3spp this one addresses the dashboard feedback in scope. One part of raised up feedback is still in progress via the following PRs:

• https://github.com/TykTechnologies/tyk-analytics/pull/3766
• [TT-11405] Updating JSON tags and field names for TLS max and min versions tyk#6078

Please review this PR for critical issues only, as the previous review has been extensive. Notable changes include:

• propper naming for some redis config options (gateway and dashboard, still in flight)
• fixes for tags references in swagger docs, indenting
• various improvements of config field docs,
• various suggested fixes by simon (no-oxford-comma, text rewordings, grammar, typos, i applied most as they were)

The tyk-docs action has been updated to:

• enable adding a branch suffix for PRs, so we can open multiple against same jira ticket (dashboard, gateway), this will make review easier due to more explicit scopes,
• updated the PR action to a newer version, as the old one did not update PR anymore (fix),
• minor PR description updates, added info about the source branch (release-5.3.0)

[dcs3spp]

Thanks @titpetric for raising Dashboard changes in a separate PR which makes reviewing easier!

I have reviewed only the changes as suggested in the PR description. For the dashboard OAS files I also made some minor suggestions for refining some OAS endpoints description and capitalising OAS endpoint / attribute descriptions in PR #4152.

I will close the previous PR (#4152 you raise a Jira ticket in the DX space and add to PR description?

[github-actions]

PR Description updated to latest commit (6e8cae8)

[github-actions]

Persistent review updated to latest commit 6e8cae8

[github-actions]

PR Code Suggestions

Category	Suggestions
Best practice	Use semantic versioning for API version updates. Consider using semantic versioning for the API version to ensure compatibility and clarity. For example, if this is a minor update without breaking changes, increment the minor version. tyk-docs/assets/others/dashboard-admin-swagger.yml [4] -version: 5.3.0 +version: 5.2.5
Enhancement	Review and minimize the required fields for updating organization details. For the updateOrg operation, ensure that all required fields are indeed necessary for every update. If some fields can be optional, consider removing them from the required list to allow partial updates. tyk-docs/assets/others/dashboard-admin-swagger.yml [1271-1286] required: - id - - owner_name - - owner_slug - - cname_enabled - - cname - - apis - - sso_enabled - - developer_quota - - developer_count - - event_options - - hybrid_enabled - - ui - - org_options_meta - - open_policy - - additional_permissions
	Simplify client requests by not requiring boolean fields that default to false. For boolean fields that default to false, consider not requiring them in the request if their absence implies false. This can simplify client requests. tyk-docs/assets/others/dashboard-admin-swagger.yml [1239-1258] cname_enabled: type: boolean + default: false sso_enabled: type: boolean + default: false hybrid_enabled: type: boolean + default: false
Maintainability	Use $ref for common property definitions to improve maintainability. To improve the maintainability of the schema definitions, consider using $ref to reference common property definitions instead of repeating them. This will make future updates easier and the document more concise. tyk-docs/assets/others/dashboard-admin-swagger.yml [1194-1198] properties: - api_human_name: - type: string - api_id: - type: string + $ref: '#/components/schemas/CommonProperties'
	Review the use of additionalProperties: false for future extensibility. Ensure that the additionalProperties: false directive is intentionally used for all schemas. This directive prevents the acceptance of unspecified fields, which can be useful for strict validation but may also limit future extensibility. tyk-docs/assets/others/dashboard-admin-swagger.yml [1199] -additionalProperties: false +additionalProperties: true

---

✨ Improve tool usage guide:

---

Overview:
The improve tool scans the PR code changes, and automatically generates suggestions for improving the PR code. The tool can be triggered automatically every time a new PR is opened, or can be invoked manually by commenting on a PR.
When commenting, to edit configurations related to the improve tool (pr_code_suggestions section), use the following template:

/improve --pr_code_suggestions.some_config1=... --pr_code_suggestions.some_config2=...

With a configuration file, use the following template:

[pr_code_suggestions]
some_config1=...
some_config2=...

Enabling\disabling automation When you first install the app, the default mode for the improve tool is: pr_commands = ["/improve --pr_code_suggestions.summarize=true", ...] meaning the improve tool will run automatically on every PR, with summarization enabled. Delete this line to disable the tool from running automatically.

Utilizing extra instructions Extra instructions are very important for the improve tool, since they enable to guide the model to suggestions that are more relevant to the specific needs of the project. Be specific, clear, and concise in the instructions. With extra instructions, you are the prompter. Specify relevant aspects that you want the model to focus on. Examples for extra instructions: [pr_code_suggestions] # /improve # extra_instructions=""" Emphasize the following aspects: - Does the code logic cover relevant edge cases? - Is the code logic clear and easy to understand? - Is the code logic efficient? ... """ Use triple quotes to write multi-line instructions. Use bullet points to make the instructions more readable.

A note on code suggestions quality While the current AI for code is getting better and better (GPT-4), it's not flawless. Not all the suggestions will be perfect, and a user should not accept all of them automatically. Suggestions are not meant to be simplistic. Instead, they aim to give deep feedback and raise questions, ideas and thoughts to the user, who can then use his judgment, experience, and understanding of the code base. Recommended to use the 'extra_instructions' field to guide the model to suggestions that are more relevant to the specific needs of the project, or use the custom suggestions 💎 tool With large PRs, best quality will be obtained by using 'improve --extended' mode.

More PR-Agent commands To invoke the PR-Agent, add a comment using one of the following commands: /review: Request a review of your Pull Request. /describe: Update the PR title and description based on the contents of the PR. /improve [--extended]: Suggest code improvements. Extended mode provides a higher quality feedback. /ask <QUESTION>: Ask a question about the PR. /update_changelog: Update the changelog based on the PR's contents. /add_docs 💎: Generate docstring for new components introduced in the PR. /generate_labels 💎: Generate labels for the PR based on the PR's contents. /analyze 💎: Automatically analyzes the PR, and presents changes walkthrough for each component. See the tools guide for more details. To list the possible configuration parameters, add a /config comment.

See the improve usage page for a more comprehensive guide on using this tool.

[titpetric]

@dcs3spp latest swagger schema updated

[dcs3spp]

PR LGTM, requires peer review before merge and release

[dcs3spp]

@titpetric I have approved would you be able to approve also and I will merge to main branch

[dcs3spp]

@titpetric I have approved PR, would you be able to approve also and I will merge to main branch

[andyo-tyk]

I've suggested some changes for incorrect use of the term "OAS" in comments in the dashboard-swagger file - however for expediency, if these require changes to the source code, we can fix these in a later patch.

[andyo-tyk]

LGTM, thanks.