[DX-1245] Tyk OAS launch notices and restructuring for 5.3

[andyo-tyk]

User description

For internal users - Please add a Jira DX PR ticket to the subject!

---

Preview Link

https://deploy-preview-4382--tyk-docs.netlify.app/docs/getting-started/

Description

This seems quite big, but is basically a reordering of pages in the Tyk Gateway and Tyk Dashboard docs, removing some that are no longer required and applying changes for Tyk OAS maturity to improve usability of the docs. Unfortunately a lot of this had to happen together. No technical content changes.

This PR replaces #4335

---

Type

enhancement, documentation

---

Description

• Updated menu structure to better organize OAS and Tyk Classic API documentation.
• Added an overview and list of request/response middleware available in Tyk.
• Updated session metadata documentation to include middleware usage.
• Introduced Tyk OAS, its benefits, and the structure of its API Definition.
• Updated the feature implementation status for Tyk OAS APIs.
• Updated glossary entries related to Tyk OAS and Classic API definitions.
• Updated Tyk Gateway feature list and descriptions.
• Added a section on logging API traffic in the basic configuration and security documentation.
• Added a warning about Tyk OAS APIs feature maturity and version compatibility in Tyk Cloud documentation.
• Added explanation on endpoint parsing for mock responses in Tyk Classic API documentation.
• Updated note on Python support in Tyk Gateway Docker images.
• Updated next step link in OAS versioning documentation.

---

Changes walkthrough

	Relevant files
Configuration changes	1 files menu.yaml Updated menu structure for OAS and Tyk Classic API documentation tyk-docs/data/menu.yaml Reorganized menu items related to OAS and Tyk Classic APIs. Removed outdated menu items. Added new menu items for Tyk OAS APIs and related concepts. +118/-138
Documentation	11 files transform-traffic.md Added overview and list of request/response middleware      tyk-docs/content/advanced-configuration/transform-traffic.md Added an overview of Tyk's request and response middleware. Listed middleware that can be applied to API requests and responses. +100/-7  session-meta-data.md Updated session metadata documentation                                      tyk-docs/content/getting-started/key-concepts/session-meta-data.md Updated overview of session metadata. Listed middleware that can use metadata. +14/-72  openapi-specification.md Introduced Tyk OAS and its API Definition structure            tyk-docs/content/getting-started/key-concepts/openapi-specification.md Introduced Tyk OAS and its benefits. Described what a Tyk OAS API Definition looks like. +21/-11  oas-reference.md Updated Tyk OAS API feature implementation status                tyk-docs/content/getting-started/using-oas-definitions/oas-reference.md Updated feature implementation status for Tyk OAS APIs. +12/-12  oas-glossary.md Updated glossary for Tyk OAS and Classic API definitions  tyk-docs/content/getting-started/using-oas-definitions/oas-glossary.md Updated definitions related to Tyk OAS and Classic API. +11/-7    tyk-gateway-features-include.md Updated Tyk Gateway feature list and description                  tyk-docs/content/shared/tyk-gateway-features-include.md Updated feature list and description for Tyk Gateway. +4/-5      basic-config-and-security.md Added section on logging API traffic                                          tyk-docs/content/basic-config-and-security.md Added a section on logging API traffic. +5/-4      first-api.md Added warning about Tyk OAS APIs feature maturity                tyk-docs/content/tyk-cloud/getting-started-tyk-cloud/first-api.md Added warning about Tyk OAS APIs feature maturity and version compatibility. +11/-6    mock-response-tyk-classic.md Added endpoint parsing explanation for mock responses        tyk-docs/content/product-stack/tyk-gateway/middleware/mock-response-tyk-classic.md Added explanation on endpoint parsing for mock responses. +10/-0    python.md Updated note on Python support in Tyk Gateway Docker images tyk-docs/content/plugins/supported-languages/rich-plugins/python/python.md Updated note on Python support in Tyk Gateway Docker images. +3/-1      oas-versioning.md Updated next step link for OAS versioning                                tyk-docs/content/getting-started/key-concepts/oas-versioning.md Updated next step link to versioning an OAS API. +1/-1

---

✨ PR-Agent usage:
Comment /help on the PR to get a list of all available PR-Agent tools and their descriptions

[netlify]

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

Name	Link
🔨 Latest commit	52d5d17
🔍 Latest deploy log	https://app.netlify.com/sites/tyk-docs/deploys/6615426854ed5f00081a4469
😎 Deploy Preview	https://deploy-preview-4382--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 Description updated to latest commit (d0f1b3f)

[github-actions]

PR Review

⏱️ Estimated effort to review [1-5]	2, because the PR mainly involves documentation restructuring and updates to reflect the new features and organization of the Tyk documentation. The changes are straightforward and mostly involve text modifications and file relocations.
🧪 Relevant tests	No
🔍 Possible issues	No
🔒 Security concerns	No

Code feedback:

---

✨ Review tool usage guide:

---

Overview:
The review tool scans the PR code changes, and generates a PR review which includes several types of feedbacks, such as possible PR issues, security threats and relevant test in the PR. More feedbacks can be added by configuring the tool.

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=...

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

[github-actions]

PR Code Suggestions

Category	Suggestions
Enhancement	Add a table of contents for easier navigation. Consider adding a table of contents at the beginning of the document for easier navigation, especially since the document has significantly expanded. This will help readers quickly find the sections most relevant to their needs. tyk-docs/content/advanced-configuration/transform-traffic.md [1-6] --- Title: Request and response middleware tags: ["middleware", "API request", "API response", "request processing", "response processing"] description: "An overview of Tyk's customisable request and response processing chain" aliases: - /transform-traffic/endpoint-designer/ --- +## Table of Contents +- [Middleware applied to the API Request](#middleware-applied-to-the-api-request) +- [Middleware applied to the API Response](#middleware-applied-to-the-api-response) +... +
	Highlight the security benefits of the "Allow list" and "Block list" middleware. For the "Allow list" and "Block list" middleware descriptions, it's beneficial to highlight the security implications more explicitly. Emphasizing security benefits can help users understand the importance of these features. tyk-docs/content/advanced-configuration/transform-traffic.md [23-29] -The [Allow List]({{< ref "product-stack/tyk-gateway/middleware/allow-list-middleware" >}}) middleware is a feature designed to restrict access to only specific API endpoints. +The [Allow List]({{< ref "product-stack/tyk-gateway/middleware/allow-list-middleware" >}}) middleware is a critical security feature designed to restrict access to only specific API endpoints, enhancing the API's security by preventing unauthorized access. ... -The [Block List]({{< ref "product-stack/tyk-gateway/middleware/block-list-middleware" >}}) middleware is a feature designed to prevent access to specific API endpoints. +The [Block List]({{< ref "product-stack/tyk-gateway/middleware/block-list-middleware" >}}) middleware is a crucial security feature designed to prevent access to specific API endpoints, further securing your API against unauthorized use.
	Simplify complex sentences for better clarity and readability. To improve the clarity and readability of the documentation, consider breaking down complex sentences into simpler, shorter sentences. This can make the documentation more accessible, especially for non-native English speakers. For example, the sentence in the "Endpoint Designer" section could be simplified for better understanding. tyk-docs/content/advanced-configuration/transform-traffic/endpoint-designer.md [42] -The **Endpoint Designer** is where you can define endpoints for your API so that you can enable and configure Tyk middleware to [perform checks and transformations]({{< ref "advanced-configuration/transform-traffic" >}}) on the API traffic. +The **Endpoint Designer** is where you define your API's endpoints. Here, you can enable and configure Tyk middleware. This middleware can [perform checks and transformations]({{< ref "advanced-configuration/transform-traffic" >}}) on the API traffic.
	Add an introductory explanation before listing components of a Tyk OAS API Definition. To enhance the documentation's clarity and ensure users understand the scope of each section, consider adding a brief introductory sentence or two before listing the components of a Tyk OAS API Definition in lines 15-31. This introduction could explain the purpose of these components and how they contribute to defining an API in Tyk. tyk-docs/content/getting-started/key-concepts/openapi-specification.md [15] ### What does a Tyk OAS API Definition look like? + +A Tyk OAS API Definition is a comprehensive blueprint for your API, detailing every aspect from authentication to request handling. It combines standard OpenAPI Specification elements with Tyk-specific configurations to provide a complete picture of how the API behaves. Below are the key components of a Tyk OAS API Definition: As part of a Tyk OAS Definition, there are a number of vendor specific fields that need to be configured. These fall into these categories:
	Improve list item capitalization for consistency. Consider using consistent capitalization for list items to maintain a professional and uniform appearance in the documentation. For example, start each list item with a capital letter. tyk-docs/content/getting-started/key-concepts/session-meta-data.md [12-14] -- to inform an admin of the provenance of a token -- values can be injected into headers for upstream services to consume (e.g. a user ID or an email address provided at the time of creation) -- values can be used in dynamic [JavaScript]... +- To inform an admin of the provenance of a token +- Values can be injected into headers for upstream services to consume (e.g., a user ID or an email address provided at the time of creation) +- Values can be used in dynamic [JavaScript]...
	Shorten the description for better readability and SEO. To enhance readability and SEO, consider shortening the description to be more concise while still conveying the essential information about session metadata. tyk-docs/content/getting-started/key-concepts/session-meta-data.md [5] -description: "Overview of session metadata" +description: "Understanding session metadata in Tyk"
	Add an introductory paragraph under the "Middleware that can use metadata" section. For better accessibility and clarity, consider adding a brief introduction or overview paragraph under the "Middleware that can use metadata" section before listing the middleware. This helps set the context for readers who may not be familiar with the concept. tyk-docs/content/getting-started/key-concepts/session-meta-data.md [18] ### Middleware that can use metadata +Metadata in Tyk can be utilized by various middleware to enhance API functionality. Below is a list of middleware that can access and use session metadata: +
	Add a table of contents for improved navigability. To improve the document's navigability and user experience, consider adding a table of contents at the beginning. This can help readers quickly find the information they're interested in, especially in longer documents. tyk-docs/content/getting-started/key-concepts/session-meta-data.md [1-3] --- date: 2017-03-23T12:58:24Z title: Session Metadata +toc: true
Best practice	Use bullet points for lists to improve readability. To improve readability and maintain consistency, consider using bullet points for listing middleware features instead of dashes. This aligns with Markdown best practices for lists. tyk-docs/content/advanced-configuration/transform-traffic.md [11-13] Within that chain are a highly configurable set of optional middleware that can, on a per-endpint basis: -- apply processing to [API requests](#middleware-applied-to-the-api-request) before they are proxied to the upstream service -- apply customisation to the [API response](#middleware-applied-to-the-api-response) prior to it being proxied back to the client +* apply processing to [API requests](#middleware-applied-to-the-api-request) before they are proxied to the upstream service +* apply customisation to the [API response](#middleware-applied-to-the-api-response) prior to it being proxied back to the client
	Use relative links for internal documentation references. Consider using relative links instead of absolute paths for internal documentation references to ensure the links remain valid even if the site's domain changes or when viewing the documentation locally. For example, instead of using {{< ref "/getting-started/using-oas-definitions/oas-reference" >}}, you can use {{< ref "getting-started/using-oas-definitions/oas-reference" >}}. tyk-docs/content/getting-started/key-concepts/high-level-concepts.md [31] -{{< ref "/getting-started/using-oas-definitions/oas-reference" >}} +{{< ref "getting-started/using-oas-definitions/oas-reference" >}}
	Match link text with the title of the target page for consistency. To ensure consistency in documentation references, consider using the same link text as the title of the target page. This helps users know what to expect when they click the link. For example, if the target page's title is "Versioning an OAS API", the link text should match this title. tyk-docs/content/getting-started/key-concepts/oas-versioning.md [77] -Go to [versioning an OAS API]({{< ref "getting-started/using-oas-definitions/versioning-an-oas-api" >}}) for an example of this feature in action. +Go to [Versioning an OAS API]({{< ref "getting-started/using-oas-definitions/versioning-an-oas-api" >}}) for an example of this feature in action.
Clarity	Rephrase the introduction to middleware chains for clarity. To enhance clarity, consider rephrasing the introduction to middleware chains. Specifically, clarify the role of middleware in request and response processing to make it more accessible to readers unfamiliar with the concept. tyk-docs/content/advanced-configuration/transform-traffic.md [9] -When you configure an API on Tyk, the Gateway will proxy all requests received at the listen path that you have defined through to the upstream (target) URL configured in the API definition. Responses from the upstream are likewise proxied on to the originating client. Requests and responses are processed through a powerful [chain of middleware]({{< ref "concepts/middleware-execution-order" >}}) that perform security and processing functions. +In Tyk, when you set up an API, the Gateway acts as an intermediary, forwarding all incoming requests to the designated upstream URL. Similarly, it forwards responses back to the client. This process involves a [chain of middleware]({{< ref "concepts/middleware-execution-order" >}}), a series of steps where each request and response can be inspected and modified for security, processing, or other purposes.
Maintainability	Add a note about the evolving nature of middleware features. To ensure the document remains up-to-date and accurate, consider adding a note or disclaimer about the potential for middleware features to evolve, encouraging readers to refer to the official Tyk documentation for the latest information. tyk-docs/content/advanced-configuration/transform-traffic.md [15] Tyk also supports a powerful custom plugin feature that enables you to add custom processing at different stages in the processing chains. For more details on custom plugins please see the [dedicated guide]({{< ref "plugins" >}}). +> **Note:** Middleware features and capabilities are subject to change. Always refer to the official Tyk documentation for the most current information. +
	Verify and correct any broken links in the documentation. For the links that are provided in the documentation, it's a good practice to verify that all links are working and lead to the correct pages. Broken links can lead to a poor user experience. If any of the links are found to be broken or leading to the wrong content, they should be updated or corrected accordingly. tyk-docs/content/advanced-configuration/transform-traffic/endpoint-designer.md [19] -- [Detailed logging]({{< ref "product-stack/tyk-gateway/basic-config-and-security/logging-api-traffic/detailed-recording#detailed-recording-with-tyk-classic-apis" >}}) +- [Detailed logging]({{< ref "corrected-link-to-detailed-logging" >}})
	Use a site-wide variable for the base URL in links for easier maintenance. To ensure the links are always up to date and reduce the maintenance burden, consider using a site-wide variable for the base URL part of the links. This way, if the base URL changes, you only need to update it in one place. tyk-docs/content/getting-started/key-concepts/session-meta-data.md [22-23] -[URL Rewrite]({{< ref "product-stack/tyk-gateway/middleware/url-rewrite-middleware#pattern" >}}) -[Request Header Transformation]({{< ref "transform-traffic/request-headers#injecting-dynamic-data-into-headers" >}}) +[URL Rewrite]({{< ref "$baseURL/product-stack/tyk-gateway/middleware/url-rewrite-middleware#pattern" >}}) +[Request Header Transformation]({{< ref "$baseURL/transform-traffic/request-headers#injecting-dynamic-data-into-headers" >}})
Accessibility	Improve image alt attributes for better accessibility. To enhance the accessibility of the documentation, consider adding descriptive text to the image alt attributes. This will help users who rely on screen readers to understand the content of the images. For example, instead of "The Tyk Classic Endpoint Designer - Core Settings tab", a more descriptive text could be "Screenshot showing the Core Settings tab in the Tyk Classic Endpoint Designer, highlighting areas to configure basic API settings." tyk-docs/content/advanced-configuration/transform-traffic/endpoint-designer.md [16] -{{< img src="/img/dashboard/endpoint-designer/classic-endpoint-designer-core.png" alt="The Tyk Classic Endpoint Designer - Core Settings tab" >}} +{{< img src="/img/dashboard/endpoint-designer/classic-endpoint-designer-core.png" alt="Screenshot showing the Core Settings tab in the Tyk Classic Endpoint Designer, highlighting areas to configure basic API settings." >}}
Readability	Break down long paragraphs into bullet points or numbered lists for better readability. To improve readability and accessibility, consider breaking down the long paragraph in lines 19-20 into bullet points or a numbered list to outline the workflow steps more clearly. tyk-docs/content/getting-started/key-concepts/high-level-concepts.md [19] -An example of the sort of flow we envisage can be seen below. One of the great things about working with Tyk OAS is that you can have a single file that you deploy across your workflow. You then iterate on that one file until you are totally happy. At this point, you can publish the ‘public’ part of the API Definition to your developer portal (i.e. exactly what a Developer needs to use the API and nothing they don’t need to see like Tyk configuration details). You can also put the whole document into source control. Since you are using a single file for the whole flow, you can add in automation to do things trigger deploying an updated API as automatically when a new version is committed into your source control. This model is very popular in GitOps and CI/CD environments. +An example of the sort of flow we envisage can be seen below: +- You start with a single file that you deploy across your workflow. +- Iterate on that one file until you are totally happy. +- Publish the ‘public’ part of the API Definition to your developer portal (i.e., exactly what a Developer needs to use the API and nothing they don’t need to see like Tyk configuration details). +- Put the whole document into source control. +- Since you are using a single file for the whole flow, you can add in automation to trigger deploying an updated API automatically when a new version is committed into your source control. +This model is very popular in GitOps and CI/CD environments.
	Use standardized markdown syntax for warnings to improve visibility and consistency. For the warning block in lines 33-41, consider using a more standardized markdown syntax for warnings if the documentation platform supports it. This could improve the visual appearance and consistency across the documentation. If the current platform does not support a specific syntax for warnings, consider using bold text or italics to highlight the warning title for better visibility. tyk-docs/content/getting-started/key-concepts/high-level-concepts.md [33-41] -{{< warning success >}} - -Warning +**Warning:** In Tyk Gateway release 5.3.0, Tyk OAS APIs gained feature maturity. Tyk will automatically migrate any pre-5.3.0 Tyk OAS APIs to the feature mature standard when you upgrade to 5.3.0 or later. Feature mature Tyk OAS APIs may not work with pre-5.3.0 versions of Tyk Gateway. It is not possible to rollback to previous versions of Tyk components with Tyk OAS APIs created in 5.3.0. For further details, please refer to the [release notes]({{< ref "product-stack/tyk-gateway/release-notes/overview" >}}) for Tyk Gateway v5.3.0. -{{< /warning >}}

---

✨ 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=...

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

[dcs3spp]

@andyo-tyk PR LGTM, I have made minor suggestions and commented reagrding if Tyk GW automatically migrates Tyk OAS API Definitions to new format or if this is just Dashboard

[dcs3spp]

Hi @andyo-tyk PR LGTM and thanks for updating PR from suggestions. I have had a final look through the PR.

The menu items have been renamed in Product Stack->Tyk Gateway (Open Source) -> Key Concepts->Tyk OAS & Tyk Classic.

Do the submenus relate to API Definitions or APIs or both? Should they be renamed as Tyk OAS API Definitions & Tyk Classic API Definitions or we could create a virtual subfolder in key concepts, something like?


Tyk API Definitions
|
|——What Is An API Definition?
|——Tyk OAS???

|——Tyk Classic API???

The key concepts overview page is a small page and for this reason has been hidden via the menu.yaml in the PR.

Maybe it should be removed and create an alias to either:


1. Product Stack -> Tyk Gateway (Open Source) -> Overview
2. Product Stack -> Tyk Gateway (Open Source) -> Key Concepts -> What is an API Definition?
   or....
3. Keep visible and expand key cooncepts overview content at a later date

[andyo-tyk]

Hi @andyo-tyk PR LGTM and thanks for updating PR from suggestions. I have had a final look through the PR.

The menu items have been renamed in Product Stack->Tyk Gateway (Open Source) -> Key Concepts->Tyk OAS & Tyk Classic.

Do the submenus relate to API Definitions or APIs or both? Should they be renamed as Tyk OAS API Definitions & Tyk Classic API Definitions or we could create a virtual subfolder in key concepts, something like?


Tyk API Definitions | |——What Is An API Definition? |——Tyk OAS???
 |——Tyk Classic API???

The key concepts overview page is a small page and for this reason has been hidden via the menu.yaml in the PR.

Maybe it should be removed and create an alias to either:


1. Product Stack -> Tyk Gateway (Open Source) -> Overview
2. Product Stack -> Tyk Gateway (Open Source) -> Key Concepts -> What is an API Definition?
   or....
3. Keep visible and expand key cooncepts overview content at a later date

I'm trying to work as much as possible within the docs structure provided by the DX team as I don't think it's right for me to propose wholesale change in this PR.

I've moved pages where they are in the wrong part of the docs structure, but otherwise trying to work with what's already there.

As it happens, the (existing) content of the Tyk Classic folder appears to be (mostly, but not entirely) a description of the fields of the Tyk Classic API Definition (for which there is no godocs-generated page, unlike Tyk OAS API Definition which is automatically documented).

The content of the Tyk OAS folder is pages that provide high level explanation of some concepts used when working with Tyk OAS - however it is neither descriptions of the Tyk OAS API definition nor of "Tyk OAS APIs" (which are instances of Tyk OAS API definitions loaded into Tyk).

Perhaps rename these to:

• Tyk OAS concepts
• Tyk Classic concepts

(though for the latter, I think the docs need some TLC - out of scope for the Tyk OAS work I've been doing)

[dcs3spp]

@andyo-tyk I've approved PR and renamed the menu items Tyk OAS Concepts and Tyk Classic Concepts and will merge and release.

[dcs3spp]

/release to release-5.3

[tykbot]

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

[tykbot]

@dcs3spp Succesfully merged PR