[DX-2144] Fixed Swagger Docs

[sharadregoti]

PR Type

Documentation

---

Description

• Add overview pages for Swagger APIs

• Improve API descriptions and guidance

• Update sidebar titles to "Overview"

• Link MD files alongside OpenAPI specs

---

Diagram Walkthrough

flowchart LR
  docsJSON["docs.json navigation"] -- "add pages + sidebar updates" --> swaggerPages["API overview MDX pages"]
  swaggerPages -- "Gateway/Dashboard/Admin/MDCB/EDP/AI Studio" --> siteDocs["Improved docs UX"]

Loading

File Walkthrough

	Relevant files
Documentation	6 files ai-studio-swagger.mdx Add AI Studio API overview and sidebar label                          +2/-1      dashboard-admin-api.mdx Add intro, auth header, image; rename sidebar                        +14/-1    tyk-edp-api.mdx Add portal API intro, auth, image; retitle                              +18/-2    tyk-dashboard-api.mdx Add dashboard API overview, security model, auth                  +31/-1    tyk-gateway-api.mdx Add gateway API overview, warnings, auth, images                  +25/-1    tyk-mdcb-api.mdx Add MDCB API description and sidebar label                              +5/-1
Configuration changes	1 files docs.json Add overview pages to API groups in nav                                    +18/-0

---

[github-actions]

PR Reviewer Guide 🔍

Here are some key observations to aid the review process:

⏱️ Estimated effort to review: 2 🔵🔵⚪⚪⚪

🧪 No relevant tests

🔒 No security concerns identified

⚡ Recommended focus areas for review Sensitive Header Format The example header uses 'admin-auth' in lowercase; verify that this exactly matches what the API expects (case-sensitive header names in docs vs. implementations) and align with any existing conventions in the docs (e.g., 'Admin-Auth' or 'Authorization'). admin-auth: Quoting Consistency Mixed use of single quotes around label text within documentation could be normalized; consider using backticks for header names/keys to be consistent with other pages and avoid ambiguity. In order to use the Dashboard API, you'll need to get the 'Tyk Dashboard API Access Credentials' secret from your user profile on the Dashboard UI. The secret you set should then be sent along as a header with each Dashboard API Request in order for it to be successful: `authorization: <your-secret>` Image Accessibility Added images lack alt text; consider adding descriptive alt attributes for accessibility and SEO while keeping current layout. <img src="https://tyk.io/docs/img/swagger_gateway_image.png" width="963" height="250"/> <img src="https://tyk.io/docs/img/swagger_gateway_direction_image.png" width="946" height="392"/>

[github-actions]

PR Code Suggestions ✨

Explore these optional code suggestions:

Category	Suggestion	Impact
Possible issue	Fix sidebar page slugs Ensure the "pages" entry matches the actual MDX slug and file path used by the docs system. If the file lives at repository root as tyk-gateway-api.mdx, keep the slug; otherwise, use the full relative path so the sidebar link doesn't 404. docs.json [395-399] +{ + "group": "Gateway", + "pages": [ + "tyk-gateway-api" + ], + "openapi": "swagger/gateway-swagger.yml" +}, - Suggestion importance[1-10]: 6 __ Why: The suggestion is contextually accurate since the PR adds a "pages" array for the Gateway group in docs.json. Verifying the slug prevents sidebar 404s, but it's a verification note and the improved_code is unchanged, so moderate impact.	Low
General	Add image alt attributes Add descriptive alt attributes to images to prevent accessibility regressions and improve SEO. Some static site generators may also warn or fail checks without alt text. tyk-gateway-api.mdx [9-10] -<img src="https://tyk.io/docs/img/swagger_gateway_image.png" width="963" height="250"/> -<img src="https://tyk.io/docs/img/swagger_gateway_direction_image.png" width="946" height="392"/> +<img src="https://tyk.io/docs/img/swagger_gateway_image.png" width="963" height="250" alt="Tyk Gateway API overview"/> +<img src="https://tyk.io/docs/img/swagger_gateway_direction_image.png" width="946" height="392" alt="Tyk Gateway request flow diagram"/> Suggestion importance[1-10]: 5 __ Why: Adding alt attributes improves accessibility and avoids potential linter warnings; the lines exist in the new hunk and the change is correct, but it's not critical to functionality.	Low
	Add trailing newline End the file with a newline to avoid formatting issues in some renderers and linters. This prevents potential concatenation with following content during build steps. ai-management/ai-studio/ai-studio-swagger.mdx [8] +This is the API for the AI Studio user and group management system. - Suggestion importance[1-10]: 3 __ Why: This is a minor formatting improvement with low functional impact; the existing_code matches the new hunk line. The improved_code is identical, indicating only a newline addition.	Low

[buger]

/release to release-5.8

[buger]

/release to release-5.10

[tykbot]

Working on it! Note that it can take a few minutes.

[tykbot]

Working on it! Note that it can take a few minutes.

[github-actions]

ℹ️ Cherry-pick skipped: no changes needed in target branch.

[github-actions]

✅ Cherry-pick successful. A PR was created and auto-merged (if allowed): #865

[tykbot]

@buger Seems like there is conflict and it require manual merge.

[tykbot]

Still working...

[tykbot]

@buger Seems like there is conflict and it require manual merge.

[sharadregoti]

/release to release-5.8

[tykbot]

Working on it! Note that it can take a few minutes.

[github-actions]

ℹ️ Cherry-pick skipped: no changes needed in target branch.

[tykbot]

@sharadregoti Seems like there is conflict and it require manual merge.