[TT-14171] Update documentation for master Dashboard #6062

buger · 2025-03-04T11:20:39Z

User description

Triggered by: lghiur

Included:

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

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

Note: Docs updates for dashboard 5.8.0 (branch suffix: docs)

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

PR Type

Enhancement
Documentation

Description

Enhanced dashboard swagger with proxy and migration endpoints.
Updated examples, headers, and response content in API spec.
Extended dashboard configuration docs with new env variables.
Added comprehensive OPA rules documentation for dashboard.

Changes walkthrough 📝

Relevant files

Enhancement

dashboard-swagger.yml `Update Swagger endpoints and add migration features.` tyk-docs/assets/others/dashboard-swagger.yml Change listen_path values for test endpoints. Add a new /api/proxy endpoint with detailed examples. Introduce /api/apis/migrate endpoint for API migrations. Update header requirements and response examples.	+450/-60

Documentation

dashboard-config.md `Extend dashboard configuration documentation.` tyk-docs/content/shared/dashboard-config.md Document new database type and connection parameters. Add configuration for table sharding in storage settings. Update Redis cluster and TLS documentation links.	+163/-4
opa-rules.md `Add comprehensive OPA rules documentation.` tyk-docs/content/tyk-dashboard/opa-rules.md Introduce new OPA rules for dashboard user permissions. Provide default, demo, and advanced OPA rule examples.	+223/-0

Need help?
Type /help how to ... in the comments thread for any questions about PR-Agent usage.
Check out the documentation for more information.

github-actions · 2025-03-04T11:22:04Z

PR Reviewer Guide 🔍

Here are some key observations to aid the review process:

⏱️ Estimated effort to review: 4 🔵🔵🔵🔵⚪
🧪 No relevant tests
🔒 No security concerns identified
⚡ Recommended focus areas for review Migration Endpoint The newly introduced /api/apis/migrate endpoint should be reviewed for comprehensive error handling and detailed response behaviors in various migration scenarios. /api/apis/migrate: post: description: Migrate APIs between Classic and OAS formats. The endpoint supports different migration modes including dry run, staging, promotion and direct migration. operationId: migrateAPI requestBody: content: application/json: schema: $ref: '#/components/schemas/MigrateAPIRequest' example: mode: "dryRun" apiIDs: [ "api123", "api456" ] abortOnFailure: true responses: "200": description: Migration completed content: application/json: schema: $ref: '#/components/schemas/MigrateAPIResponse' "400": description: Bad request - validation failed content: application/json: schema: $ref: '#/components/schemas/ApiResponse' "401": description: Unauthorized content: application/json: schema: $ref: '#/components/schemas/ApiResponse' summary: Migrate APIs between Classic and OAS formats tags: - MigrateOAS Schema Definitions The additions of new schema definitions (e.g., ProxyRequest, ProxyResponse, ErrorResponse, MigrateAPIRequest, and MigrateAPIResponse) should be validated to ensure they align with the intended API contract and include necessary validations. in: query name: start_day schema: format: date type: string schemas: ProxyRequest: type: object required: - method - url properties: method: type: string description: HTTP method for the proxy request (GET, POST, PUT, DELETE, etc.) url: type: string description: Full URL for the proxy request (valid Gateway url), including scheme, host, and path headers: type: object additionalProperties: type: string description: Headers to be sent with the proxy request body: type: object description: Body of the proxy request, typically used for POST or PUT requests ProxyResponse: type: object properties: status_code: type: integer description: HTTP status code of the proxied response headers: type: object additionalProperties: type: string description: Headers received from the proxied response body: type: object description: Body of the proxied response, parsed as JSON if possible ErrorResponse: type: object properties: Status: type: string description: Error status, typically "Error" Message: type: string description: Detailed error message explaining what went wrong Meta: type: object nullable: true description: Additional metadata about the error, if available APICertificateStatusMessage: Documentation Consistency The newly added configuration sections for various database parameters need to be checked for consistency with existing docs and ensure that all ENV variable examples and descriptions are accurate and easy to follow. ### storage.main Main database where the dashboard resources are stored (users, orgs, policies, etc) ### storage.main.type ENV: <b>TYK_DB_STORAGE_MAIN_TYPE</b><br /> Type: `DBType`<br /> Type is the type of the database. Possible values are: - "mongo": Use MongoDB. - "postgres": Use PostgreSQL. - "mysql": Use MySQL. ### storage.main.connection_string ENV: <b>TYK_DB_STORAGE_MAIN_CONNECTIONSTRING</b><br /> Type: `string`<br /> ConnectionString is the connection string for the database. Overrides ReadConnectionString and WriteConnectionString. ### storage.main.read_connection_string ENV: <b>TYK_DB_STORAGE_MAIN_READCONNECTIONSTRING</b><br /> Type: `string`<br /> ReadConnectionString is the connection string for read operations. Only used if ConnectionString is not set. ### storage.main.write_connection_string ENV: <b>TYK_DB_STORAGE_MAIN_WRITECONNECTIONSTRING</b><br /> Type: `string`<br /> WriteConnectionString is the connection string for write operations. Only used if ConnectionString is not set. ### storage.main.mongo

github-actions · 2025-03-04T11:22:45Z

PR Code Suggestions ✨

Explore these optional code suggestions:

Category	Suggestion	Impact
Possible issue	Fix sprintf argument mismatch Update the sprintf format string in the deny rules so that the number of format specifiers matches the provided arguments. tyk-docs/content/tyk-dashboard/opa-rules.md [128] -x := sprintf("You do not have permission to carry out '%v' operation.", [request_intent, input.request.path]) +x := sprintf("You do not have permission to carry out '%v' operation on '%v'.", [request_intent, input.request.path]) Suggestion importance[1-10]: 8 __ Why: The suggestion correctly identifies the sprintf format mismatch, ensuring that the format string includes two placeholders to match the two arguments provided. This change improves the correctness of the rule and avoids potential runtime errors.	Medium

netlify · 2025-03-04T11:22:46Z

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

Name	Link
🔨 Latest commit	`5054ff1`
🔍 Latest deploy log	https://app.netlify.com/sites/tyk-docs/deploys/67c6e20afd05200008c0ee19
😎 Deploy Preview	https://deploy-preview-6062--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.

netlify · 2025-03-04T11:22:47Z

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

Name	Link
🔨 Latest commit	`5054ff1`
🔍 Latest deploy log	https://app.netlify.com/sites/tyk-docs/deploys/67c6e20afd05200008c0ee19
😎 Deploy Preview	https://deploy-preview-6062--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.

andyo-tyk

Suggested improvements to wording. We shouldn't use the term "OAS API" when referring to a Tyk OAS API.

andyo-tyk · 2025-03-04T14:40:12Z

tyk-docs/assets/others/dashboard-swagger.yml

@@ -3946,6 +4052,42 @@ paths:
      summary: List OAuth client tokens.
      tags:
      - Oauth
+  /api/apis/migrate:
+    post:
+      description: Migrate APIs between Classic and OAS formats. The endpoint supports different migration modes including dry run, staging, promotion and direct migration.


Suggested change

description: Migrate APIs between Classic and OAS formats. The endpoint supports different migration modes including dry run, staging, promotion and direct migration.

description: Migrate APIs from Tyk Classic to Tyk OAS format. The endpoint supports different migration modes including dry run, staging, promotion and direct migration.

andyo-tyk · 2025-03-04T14:40:43Z

tyk-docs/assets/others/dashboard-swagger.yml

+            application/json:
+              schema:
+                $ref: '#/components/schemas/ApiResponse'
+      summary: Migrate APIs between Classic and OAS formats


Suggested change

summary: Migrate APIs between Classic and OAS formats

summary: Migrate APIs from Tyk Classic to Tyk OAS format

andyo-tyk · 2025-03-04T14:41:34Z

tyk-docs/assets/others/dashboard-swagger.yml

+              scheme: bearer
+              type: http
+        info:
+          description: This is a sample OAS.


Suggested change

description: This is a sample OAS.

description: This is a sample OpenAPI description.

andyo-tyk · 2025-03-04T14:41:55Z

tyk-docs/assets/others/dashboard-swagger.yml

+              type: http
+        info:
+          description: This is a sample OAS.
+          title: OAS Sample


Suggested change

title: OAS Sample

title: Sample OpenAPI description

andyo-tyk · 2025-03-04T14:42:33Z

tyk-docs/assets/others/dashboard-swagger.yml

+        servers:
+          - url: https://localhost:8080
+    PatchOASExample:
+      summary: Patch Tyk Oas Example


Suggested change

summary: Patch Tyk Oas Example

summary: Patch Tyk OAS Example

andyo-tyk · 2025-03-04T14:42:55Z

tyk-docs/assets/others/dashboard-swagger.yml

+              scheme: bearer
+              type: http
+        info:
+          description: This is a sample OAS.


Suggested change

description: This is a sample OAS.

description: This is a sample OpenAPI description.

andyo-tyk · 2025-03-04T14:43:12Z

tyk-docs/assets/others/dashboard-swagger.yml

+              type: http
+        info:
+          description: This is a sample OAS.
+          title: OAS Sample


Suggested change

title: OAS Sample

title: Sample OpenAPI description

andyo-tyk · 2025-03-04T14:45:59Z

tyk-docs/content/shared/dashboard-config.md

@@ -916,6 +1066,15 @@ Type: `bool`<br />

 Temporary : Enable dev mode feature on UI

+### ui.onboarding
+Onboarding section defines the information about the onboarding UI wizzard flow.


Suggested change

Onboarding section defines the information about the onboarding UI wizzard flow.

Onboarding section controls the onboarding quick start wizard.

andyo-tyk · 2025-03-04T14:46:25Z

tyk-docs/content/shared/dashboard-config.md

+ENV: <b>TYK_DB_UI_ONBOARDING_ENABLED</b><br />
+Type: `bool`<br />
+
+Enabled is a boolean flag that enables the onboarding UI wizzard flow.


Suggested change

Enabled is a boolean flag that enables the onboarding UI wizzard flow.

Enabled is a boolean flag that enables the onboarding quick start wizard.

sharadregoti · 2025-03-05T05:30:07Z

tyk-docs/content/shared/dashboard-config.md

@@ -110,6 +110,37 @@ This option allows you to store different types of data in different databases.
 ### storage.main
 Main database where the dashboard resources are stored (users, orgs, policies, etc)

+### storage.main.type


Hey, @lghiur

Could you check why the streaming configuration isn't available here? I'm specifically looking for this variable, TYK_DB_STREAMING_ENABLED. There's also a Jira ticket open for the same issue.

@lghiur, were you able to check the issue?

tyk-docs/assets/others/dashboard-swagger.yml

sharadregoti · 2025-03-05T05:42:22Z

tyk-docs/content/tyk-dashboard/opa-rules.md

@@ -0,0 +1,223 @@
+---


During docs consolidation, this page was removed, and the content was moved to this page.

I'll fix this part.

@sharadregoti you need to update the script the moves the files over to docs. is this how you're planning to fix it?

Hey, Can you point me to the Github Action /Script that generates opa-rules file? I cannot find it in the tyk-config-generator repo

TykTechnologies/exp@6d6dbe9

sharadregoti · 2025-03-05T05:46:07Z

tyk-docs/assets/others/dashboard-swagger.yml

      requestBody:
        content:
          application/json:
            examples:
              ImportByUrl:
                summary: Import By Url
                value:
-                  url: https://gist.githubusercontent.com/Keithwachira/e4f11baefb68f2ace5dd2297b7ccc3e0/raw/bd0aeee05d1bd380535af7a8d5d59aa30f9b5aad/tykOas.json
+                  url: https://gist.githubusercontent.com/yurisasuke/e4f11baefb68f2ace5dd2297b7ccc3e0/raw/bb476fa4d4a48874b26d9df9bf62094d1a07f040/tykOas.json


Should we use personal github URLs like this?

the previous one was also on private gist, would say to revise this at a later point

Ok, can you create a Jira ticket for the same? in the product board

sharadregoti · 2025-03-11T06:37:16Z

Closing this in favor of #6084

Import config/docs

5054ff1

github-actions bot added the Review effort 4/5 label Mar 4, 2025

lghiur changed the title ~~[TT-14171] Update documentation for master~~ [TT-14171] Update documentation for master Dashboard Mar 4, 2025

andyo-tyk requested changes Mar 4, 2025

View reviewed changes

sharadregoti requested changes Mar 5, 2025

View reviewed changes

sharadregoti added Awaiting Resolve Comments 5.8.0 labels Mar 7, 2025

sharadregoti closed this Mar 11, 2025

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

[TT-14171] Update documentation for master Dashboard #6062

[TT-14171] Update documentation for master Dashboard #6062

buger commented Mar 4, 2025 •

edited by github-actions bot

Loading

github-actions bot commented Mar 4, 2025

github-actions bot commented Mar 4, 2025

netlify bot commented Mar 4, 2025

netlify bot commented Mar 4, 2025 •

edited

Loading

andyo-tyk left a comment

andyo-tyk Mar 4, 2025

andyo-tyk Mar 4, 2025

andyo-tyk Mar 4, 2025

andyo-tyk Mar 4, 2025

andyo-tyk Mar 4, 2025

andyo-tyk Mar 4, 2025

andyo-tyk Mar 4, 2025

andyo-tyk Mar 4, 2025

andyo-tyk Mar 4, 2025

sharadregoti Mar 5, 2025

sharadregoti Mar 7, 2025

sharadregoti Mar 5, 2025

lghiur Mar 6, 2025

sharadregoti Mar 7, 2025

lghiur Mar 11, 2025

sharadregoti Mar 5, 2025

lghiur Mar 6, 2025

sharadregoti Mar 7, 2025

sharadregoti Mar 11, 2025

sharadregoti commented Mar 11, 2025

	description: Migrate APIs between Classic and OAS formats. The endpoint supports different migration modes including dry run, staging, promotion and direct migration.
	description: Migrate APIs from Tyk Classic to Tyk OAS format. The endpoint supports different migration modes including dry run, staging, promotion and direct migration.

	summary: Migrate APIs between Classic and OAS formats
	summary: Migrate APIs from Tyk Classic to Tyk OAS format

	description: This is a sample OAS.
	description: This is a sample OpenAPI description.

	summary: Patch Tyk Oas Example
	summary: Patch Tyk OAS Example

	Onboarding section defines the information about the onboarding UI wizzard flow.
	Onboarding section controls the onboarding quick start wizard.

	Enabled is a boolean flag that enables the onboarding UI wizzard flow.
	Enabled is a boolean flag that enables the onboarding quick start wizard.

[TT-14171] Update documentation for master Dashboard #6062

[TT-14171] Update documentation for master Dashboard #6062

Conversation

buger commented Mar 4, 2025 • edited by github-actions bot Loading

User description

PR Type

Description

Changes walkthrough 📝

github-actions bot commented Mar 4, 2025

PR Reviewer Guide 🔍

github-actions bot commented Mar 4, 2025

PR Code Suggestions ✨

netlify bot commented Mar 4, 2025

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

netlify bot commented Mar 4, 2025 • edited Loading

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

andyo-tyk left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

sharadregoti commented Mar 11, 2025

buger commented Mar 4, 2025 •

edited by github-actions bot

Loading

netlify bot commented Mar 4, 2025 •

edited

Loading