Merging to release-5.6.0: [TT-13109]Generate New Swagger and Update Validator for Gateway (#6231)

[buger]

User description

TT-13109Generate New Swagger and Update Validator for Gateway (#6231)

User description

This pull request contains :

1. The new gateway swagger
2. A new linter
3. And a readme of how to generate the swagger
   .

.This provides the documentation on how you can generate the gateway
Open Api specification. It contains a read me with all the steps to
generate the OAS.

The OAS code is in this pr :
#6123
TT-13109

---

Type

Documentation

---

Description

• Added a comprehensive README.md in the tyk-api-documentation
  directory.
• The documentation includes details on the version of OAS used, the
  tooling (Redocly), and the library (openapi-go) for OAS generation.
• Step-by-step instructions are provided for generating the Swagger.yml
  file using a make command in the specified repository branch.
• Describes the file structure within the Swagger directory, explaining
  the organization of files by OAS tags and the roles of various files in
  the generation process.

---

Changes walkthrough

	Relevant files
Documentation	README.md Add Documentation for Generating Tyk API Swagger File        tyk-api-documentation/README.md Introduced a new README.md for Tyk API Documentation. Detailed the process and tools used to generate the Open API Specification (OAS). Provided step-by-step instructions on how to generate the Swagger.yml file. Explained the file structure within the Swagger directory. +33/-0

---

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

---

Co-authored-by: Yaara yaara@tyk.io

---

PR Type

Documentation, Enhancement

---

Description

• Added a new GitHub Actions workflow to lint and validate the Swagger schema using Redocly CLI, enhancing the CI/CD process.
• Introduced a diff mechanism to compare changes in the Swagger YAML file, providing better visibility into API changes.
• Created a Redocly lint ignore configuration to handle specific Swagger paths and media type examples, improving linting accuracy.
• Added comprehensive documentation on generating the Tyk API Swagger file, including instructions and file structure details.
• Configured Redocly linting rules to enforce best practices and error handling in the OpenAPI specification.

---

Changes walkthrough 📝

	Relevant files
Enhancement	lint-swagger.yml Add GitHub Actions workflow for Swagger linting and diffing .github/workflows/lint-swagger.yml Added a new GitHub Actions workflow for linting Swagger schema. Integrated Redocly CLI for OpenAPI validation. Implemented a diff mechanism to compare Swagger YAML changes. +95/-9
Configuration changes	.redocly.lint-ignore.yaml Add Redocly lint ignore configuration for Swagger                .redocly.lint-ignore.yaml Created a Redocly lint ignore file for specific Swagger paths. Ignored ambiguous paths and invalid media type examples. +42/-0    redocly.yml Configure Redocly linting rules for Swagger validation      redocly.yml Added Redocly configuration file with linting rules. Defined rules for unresolved references, unused components, and more. +56/-0
Documentation	swagger.md Add documentation for generating Tyk API Swagger file        docs/swagger.md Added documentation for Tyk API OpenAPI specification. Included instructions for generating Swagger YAML file. Described file structure and generation process. +34/-0
Additional files (token-limit)	swagger.yml ...                                                                                                            swagger.yml ... +7158/-3355

---

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

[github-actions]

Swagger Changes

Changes in swagger.yml too large (line count 4303), check CI lint action for differences

[github-actions]

API Changes

no api changes detected

[github-actions]

PR Reviewer Guide 🔍

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

🧪 No relevant tests

🔒 No security concerns identified

⚡ Key issues to review Dependency Management The PR installs the @redocly/cli globally using npm, which might lead to version conflicts or unexpected behavior in different environments. Consider using a local installation or a Docker container to ensure consistent tooling versions across environments. Hardcoded Token Usage The workflow script directly uses a GitHub token within the script. It's recommended to use secrets or environment variables for such sensitive information to enhance security and maintainability. Error Handling The script sets '+e' which might suppress important errors. Consider handling errors more explicitly to avoid masking issues during the execution of the workflow.

[github-actions]

PR Code Suggestions ✨

Category	Suggestion	Score
Maintainability	Implement robust error handling for dyff commands to ensure errors are properly managed Use a more robust error handling mechanism for the dyff command to ensure that any errors are properly handled and logged. .github/workflows/lint-swagger.yml [71-73] -set +e -dyff between -c on --ignore-whitespace-changes -i swagger-prev.yml swagger-current.yml -dyff between -c off --ignore-whitespace-changes -i swagger-prev.yml swagger-current.yml | egrep -v '^ . ' | sort > changes.txt +set -e +if ! dyff between -c on --ignore-whitespace-changes -i swagger-prev.yml swagger-current.yml; then + echo "Error comparing current and previous swagger files" + exit 1 +fi +if ! dyff between -c off --ignore-whitespace-changes -i swagger-prev.yml swagger-current.yml | egrep -v '^ . ' | sort > changes.txt; then + echo "Error generating change log" + exit 1 +fi Suggestion importance[1-10]: 10 Why: Robust error handling is crucial for maintainability and reliability, ensuring that any issues are properly logged and managed, which is vital for a stable CI/CD pipeline.	10
Performance	Use a pre-built binary for dyff to simplify the setup and reduce build times Instead of cloning the repository and installing from source, consider using a pre-built binary or package for dyff to reduce build times and complexity. .github/workflows/lint-swagger.yml [50-51] -git clone --depth=1 https://github.com/aoktox/dyff -cd dyff && go install ./cmd/... +curl -sSL https://github.com/aoktox/dyff/releases/download/v1.0.0/dyff_$(uname -s)_$(uname -m).tar.gz | tar xz -C /usr/local/bin Suggestion importance[1-10]: 9 Why: Using a pre-built binary reduces complexity and build times, which can significantly enhance performance and efficiency in the CI process.	9
Best practice	Use a local installation of @redocly/cli to avoid conflicts and ensure reproducibility Replace the global installation of @redocly/cli with a local installation to avoid potential conflicts with other actions or dependencies in the workflow. .github/workflows/lint-swagger.yml [22] -npm install @redocly/cli -g +npm install @redocly/cli Suggestion importance[1-10]: 8 Why: Using a local installation of @redocly/cli can prevent potential conflicts with other dependencies and actions, improving the reliability and reproducibility of the workflow.	8
	Specify a more precise Node.js version to ensure stable and predictable CI builds Consider using a more specific version of Node.js rather than the latest major version to ensure compatibility and predictability in your CI workflows. .github/workflows/lint-swagger.yml [19] -node-version: 20 +node-version: '20.x' Suggestion importance[1-10]: 7 Why: Specifying a more precise Node.js version helps ensure compatibility and predictability, which is a good practice for CI workflows. However, it is not a critical issue.	7

[sonarcloud]

Quality Gate passed

Issues
0 New issues
0 Accepted issues

Measures
0 Security Hotspots
0.0% Coverage on New Code
0.0% Duplication on New Code

See analysis details on SonarCloud