docs(DX-2061): add environment variable type mapping documentation

[buger]

User description

Summary

• Add a centralized snippet (snippets/env-type-mapping.mdx) explaining how Go types map to environment variable formats
• This clarifies the expected format for array types like []string, which should be comma-separated values rather than JSON arrays
• The snippet is included in all configuration documentation pages for consistency

Context

This PR addresses the confusion reported in DX-2061, where the documentation for TYK_PMP_PUMPS_STDOUT_FILTERS_SKIPPEDAPIIDS (type []string) was unclear, potentially leading users to incorrectly use JSON array format when a comma-separated string is expected.

Changes

New Files

• snippets/env-type-mapping.mdx - A reusable snippet with a type mapping table

Modified Files

• tyk-oss-gateway/configuration.mdx
• tyk-dashboard/configuration.mdx
• tyk-pump/tyk-pump-configuration/tyk-pump-environment-variables.mdx
• tyk-multi-data-centre/mdcb-configuration-options.mdx
• tyk-configuration-reference/tyk-identity-broker-configuration.mdx
• product-stack/tyk-enterprise-developer-portal/deploy/configuration.mdx

Test Plan

• Verify the snippet renders correctly on each documentation page
• Confirm the type mapping table is clear and accurate
• Test that the documentation builds without errors

Closes DX-2061

🤖 Generated with Claude Code

---

PR Type

Documentation

---

Description

• Add reusable env type mapping snippet

• Include snippet across config docs

• Clarify []string uses comma-separated values

• Document map and JSON formatting rules

---

Diagram Walkthrough

flowchart LR
  SNIPPET["New snippet: env-type-mapping.mdx"]
  GW["Gateway configuration docs"]
  DB["Dashboard configuration docs"]
  PUMP["Pump configuration docs"]
  MDCB["MDCB configuration docs"]
  TIB["Identity Broker configuration docs"]
  PORTAL["Enterprise Developer Portal configuration docs"]

  SNIPPET -- "import + <EnvTypeMapping/>" --> GW
  SNIPPET -- "import + <EnvTypeMapping/>" --> DB
  SNIPPET -- "import + <EnvTypeMapping/>" --> PUMP
  SNIPPET -- "import + <EnvTypeMapping/>" --> MDCB
  SNIPPET -- "import + <EnvTypeMapping/>" --> TIB
  SNIPPET -- "import + <EnvTypeMapping/>" --> PORTAL

Loading

File Walkthrough

Relevant files

Documentation

7 files env-type-mapping.mdx Add reusable environment variable type mapping table          +16/-0    configuration.mdx Import and render env type mapping snippet                              +3/-0      configuration.mdx Import and insert env type mapping guidance                            +3/-0      tyk-pump-environment-variables.mdx Add env type mapping to Pump config docs                                  +3/-0      mdcb-configuration-options.mdx Include env type mapping in MDCB docs                                        +3/-0      tyk-identity-broker-configuration.mdx Insert env type mapping into TIB config page                          +4/-0      configuration.mdx Import and display env type mapping in Portal docs              +5/-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 Accuracy Confirm that the example for map[string]interface{} uses the correct env var path and key names (e.g., "policies.policy_source.config") and that the JSON example reflects actual accepted structure for that component. | `map[string]string` | A comma-separated list of key:value pairs. | `TYK_GW_GLOBALHEADERS="X-Tyk-Test:true,X-Tyk-Version:1.0"` | | `map[string]interface{}` | A JSON string representing the object. | `TYK_GW_POLICIES_POLICYSOURCE_CONFIG='{"connection_string": "..."}'` | Edge Cases Clarify escaping and quoting for values containing commas or colons in []string and map[string]string to avoid parsing errors; consider adding an example with embedded commas/colons. | `[]string` | A comma-separated list of strings. | `TYK_PMP_PUMPS_STDOUT_FILTERS_SKIPPEDAPIIDS="api1,api2,api3"` | | `map[string]string` | A comma-separated list of key:value pairs. | `TYK_GW_GLOBALHEADERS="X-Tyk-Test:true,X-Tyk-Version:1.0"` | | `map[string]interface{}` | A JSON string representing the object. | `TYK_GW_POLICIES_POLICYSOURCE_CONFIG='{"connection_string": "..."}'` | <Note> For complex types like `map[string]interface{}`, the value should be a valid JSON string. For `[]string` and `map[string]string`, ensure there are no spaces around the commas unless they are part of the value itself. Placement Verify the snippet placement does not disrupt heading hierarchy or duplicate existing explanations; ensure surrounding text doesn’t conflict with the new guidance. <EnvTypeMapping/> Environment variables (env var) can be used to override the settings defined in the configuration file. Where an environment variable is specified, its value will take precedence over the value in the configuration file.

[github-actions]

PR Code Suggestions ✨

Explore these optional code suggestions:

Category	Suggestion	Impact
General	Add shell-specific quoting guidance Warn about shell quoting to preserve valid JSON and avoid variable expansion. Recommend single quotes in POSIX shells and show Windows PowerShell/CMD variants to prevent broken JSON. snippets/env-type-mapping.mdx [12] -| `map[string]interface{}` | A JSON string representing the object. | `TYK_GW_POLICIES_POLICYSOURCE_CONFIG='{"connection_string": "..."}'` | +| `map[string]interface{}` | A JSON string representing the object. Use shell-appropriate quoting to preserve JSON (POSIX: single quotes; PowerShell: single quotes; CMD: escape quotes). | POSIX: `TYK_GW_POLICIES_POLICYSOURCE_CONFIG='{"connection_string":"..."}'` • PowerShell: `$env:TYK_GW_POLICIES_POLICYSOURCE_CONFIG='{"connection_string":"..."}'` • CMD: `set TYK_GW_POLICIES_POLICYSOURCE_CONFIG={\"connection_string\":\"...\"}` | Suggestion importance[1-10]: 7 __ Why: Shell-quoting nuances for JSON env values are important and commonly problematic; the examples align with the existing row and improve cross-shell correctness. Still documentation-focused, not a code bug fix.	Medium
	Clarify comma handling in lists Clarify how to include commas within values to prevent accidental splitting. Add guidance about quoting and escaping to avoid misparsing when values contain commas. snippets/env-type-mapping.mdx [10] -| `[]string` | A comma-separated list of strings. | `TYK_PMP_PUMPS_STDOUT_FILTERS_SKIPPEDAPIIDS="api1,api2,api3"` | +| `[]string` | A comma-separated list of strings. (If a value contains a comma, wrap the entire env value in quotes and escape commas as needed by your shell.) | `TYK_PMP_PUMPS_STDOUT_FILTERS_SKIPPEDAPIIDS="api1\,part,api2,api3"` | Suggestion importance[1-10]: 6 __ Why: Adds useful guidance on commas within list values which can prevent misparsing, and the improved snippet matches the referenced table row. Impact is moderate as it's documentation clarity rather than a functional bug.	Low
	Document escaping for maps Specify how to handle colons and commas inside keys/values and whitespace trimming to avoid parsing errors. Add a note that values with commas or colons should be quoted/escaped appropriately. snippets/env-type-mapping.mdx [11] -| `map[string]string` | A comma-separated list of key:value pairs. | `TYK_GW_GLOBALHEADERS="X-Tyk-Test:true,X-Tyk-Version:1.0"` | +| `map[string]string` | A comma-separated list of key:value pairs (`key:value`). Keys/values are trimmed; to include commas/colons, quote or escape them per your shell. | `TYK_GW_GLOBALHEADERS="X-Custom:\"a\,b:c\",X-Tyk-Version:1.0"` | Suggestion importance[1-10]: 6 __ Why: Clarifies handling of commas/colons and whitespace in map env vars; relevant to the shown row and helps avoid configuration errors. It's accurate but mainly an explanatory enhancement.	Low

[buger]

/release to release-5.8

[buger]

/release to release-5.10

[github-actions]

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

[github-actions]

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