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

buger commented 2 months ago

User description

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

User description

This pull request contains :

The new gateway swagger
A new linter
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 : https://github.com/TykTechnologies/tyk/pull/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

DX-1272: https://tyktech.atlassian.net/browse/DX-1272?atlOrigin=eyJpIjoiNWRkNTljNzYxNjVmNDY3MDlhMDU5Y2ZhYzA5YTRkZjUiLCJwIjoiZ2l0aHViLWNvbS1KU1cifQ

TT-13109: https://tyktech.atlassian.net/browse/TT-13109?atlOrigin=eyJpIjoiNWRkNTljNzYxNjVmNDY3MDlhMDU5Y2ZhYzA5YTRkZjUiLCJwIjoiZ2l0aHViLWNvbS1KU1cifQ

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[bot] commented 2 months ago

Swagger Changes

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

github-actions[bot] commented 2 months ago

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[bot] commented 2 months ago

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]](https://github.com/TykTechnologies/tyk/pull/6541/files#diff-211d7beb5c2247bdb14cd6aaa6da2feb35176618e91541850a5f4eebf736990dR34-R34) ```diff -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]](https://github.com/TykTechnologies/tyk/pull/6541/files#diff-211d7beb5c2247bdb14cd6aaa6da2feb35176618e91541850a5f4eebf736990dR19-R19) ```diff -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]](https://github.com/TykTechnologies/tyk/pull/6541/files#diff-211d7beb5c2247bdb14cd6aaa6da2feb35176618e91541850a5f4eebf736990dR50-R51) ```diff -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]](https://github.com/TykTechnologies/tyk/pull/6541/files#diff-211d7beb5c2247bdb14cd6aaa6da2feb35176618e91541850a5f4eebf736990dR60-R66) ```diff 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