Merging to release-5.6: [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 GitHub Actions workflow to lint and validate Swagger schema using Redocly CLI, and to diff Swagger YAML files for changes.
• Introduced a Redocly lint ignore file to specify paths and rules to ignore during linting.
• Added comprehensive documentation on generating the Tyk API Swagger file, including instructions for using Redocly and openapi-go.
• Configured Redocly linting rules to enforce best practices and error handling in OpenAPI specifications.

---

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 using Redocly CLI. Introduced a job to diff Swagger YAML files and post comments on PRs. Configured the workflow to run on changes to swagger.yml. +95/-9
Configuration changes	.redocly.lint-ignore.yaml Introduce Redocly lint ignore configuration                            .redocly.lint-ignore.yaml Added a Redocly lint ignore configuration file. Specified paths and rules to ignore during linting. +42/-0    redocly.yml Add Redocly configuration for OpenAPI linting                        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 Tyk API Swagger generation                  docs/swagger.md Added documentation for generating Tyk API Swagger file. Included instructions for using Redocly and openapi-go. Described the 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]

PR Reviewer Guide 🔍

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

🧪 No relevant tests

🔒 No security concerns identified

⚡ Key issues to review Possible Bug The redocly lint command in line 23 might fail if the redocly.yml configuration file is not correctly set up or missing required rules. Ensure that all configurations and dependencies are correctly specified. Security Concern The use of a GitHub token in the environment variable in line 32 could expose sensitive information if not handled securely. Ensure that the token is used securely and that permissions are limited.

[github-actions]

PR Code Suggestions ✨

Category	Suggestion	Score
Security	Securely include the token in Git requests without exposing it in the URL To enhance security, avoid exposing tokens in the repository URL. Use the extraheader option in git config to securely include the token in requests. .github/workflows/lint-swagger.yml [34] -git config --global url."https://${TOKEN}@github.com".insteadOf "https://github.com" +git config --global http.extraheader "AUTHORIZATION: bearer ${TOKEN}" Suggestion importance[1-10]: 9 Why: This suggestion addresses a significant security concern by preventing token exposure in URLs, which is crucial for protecting sensitive information in CI/CD environments.	9
Best practice	Use a specific node version instead of the latest major version Consider using a more specific node version instead of the latest major version to ensure consistent behavior across all runs. Using a specific version helps avoid potential issues due to unexpected changes in new releases. .github/workflows/lint-swagger.yml [19] -node-version: 20 +node-version: '20.0.0' # Specify a full version number Suggestion importance[1-10]: 7 Why: Specifying a full node version number can help ensure consistent behavior across different runs, avoiding potential issues from unexpected changes in new releases. This is a good practice for maintaining stability in CI/CD workflows.	7
	Use a pre-built GitHub Action or Docker image for installing dyff Instead of cloning and installing dyff manually, consider using a pre-built action or a Docker image if available. This approach can reduce the complexity of your workflow and improve the reliability and speed of your setup. .github/workflows/lint-swagger.yml [50-51] -git clone --depth=1 https://github.com/aoktox/dyff -cd dyff && go install ./cmd/... +- uses: some-org/dyff-action@v1 Suggestion importance[1-10]: 6 Why: Using a pre-built action or Docker image can simplify the workflow, reduce complexity, and improve reliability and speed. However, the suggestion assumes the availability of such an action or image, which may not always be the case.	6
	Add a cleanup step to remove temporary files after use Consider adding a cleanup step to remove the swagger-current.yml and swagger-prev.yml files after they are no longer needed. This can help manage disk space and ensure that sensitive data does not persist in the workspace. .github/workflows/lint-swagger.yml [60-66] cp swagger.yml swagger-current.yml ... cp swagger.yml swagger-prev.yml +... +- name: Cleanup + run: rm -f swagger-current.yml swagger-prev.yml Suggestion importance[1-10]: 5 Why: Adding a cleanup step is a good practice for managing disk space and ensuring sensitive data does not persist unnecessarily. However, it is a minor improvement and not critical to the workflow's functionality.	5

[github-actions]

API Changes

no api changes detected

[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