[DX-1272]add documentation for generating the swagger

[yurisasuke]

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 : https://github.com/TykTechnologies/tyk/pull/6123 DX-1272

---

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

[github-actions[bot]]

API Changes

no api changes detected

[github-actions[bot]]

PR Description updated to latest commit (https://github.com/TykTechnologies/tyk/commit/06a05b022586d927cab69eb13032e7ade46bb04b)

[github-actions[bot]]

PR Review

⏱️ Estimated effort to review [1-5]	2, because the PR is primarily focused on adding documentation. The content is straightforward and mainly involves explaining the process and tools used for generating the Open API Specification. The complexity is low, and the main effort would be in verifying the accuracy of the instructions and the clarity of the documentation.
🧪 Relevant tests	No
🔍 Possible issues	Possible Typo: The sentence "It supports producing OASn for version 3. (Golang doesn't to many libraries to produce OAS three)" seems to contain a typo or grammatical error. It should be corrected for clarity.
🔒 Security concerns	No

Code feedback:

---

relevant file	tyk-api-documentation/README.md
suggestion	Consider correcting the grammatical error in the sentence about the openapi-go library. It currently reads, "It supports producing OASn for version 3. (Golang doesn't to many libraries to produce OAS three)", which might be confusing. A clearer version could be: "It supports producing OAS for version 3.0, as there are not many Golang libraries that offer this capability." [important]
relevant line	1. It supports producing OASn for version 3. (Golang doesn't to many libraries to produce OAS three)

---

---

✨ 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[bot]]

PR Code Suggestions

Category	Suggestions
Enhancement	Correct a typo in the documentation. Correct the typo in the word "tehn" to "then" to improve the readability and professionalism of the documentation. tyk-api-documentation/README.md [33] -. We tehn have a cmd directory that has the main.go file (used to call all tge generation functions), we also have a makefile and the generated swagger.yaml file . +. We then have a cmd directory that has the main.go file (used to call all the generation functions), we also have a makefile and the generated swagger.yaml file.
	Correct a grammatical error in the documentation. Correct the grammatical error in the phrase "Golang doesn't to many libraries to produce OAS three" to make it clear and grammatically correct. tyk-api-documentation/README.md [15] -1. It supports producing OASn for version 3. (Golang doesn't to many libraries to produce OAS three) +1. It supports producing OAS for version 3. (Golang doesn't have many libraries to produce OAS three)
	Clarify the command description and correct a typo. Clarify the description of the make generate command to enhance understanding and correct the typo "it will then generate". tyk-api-documentation/README.md [27-28] -. The generate command is defined as: `rm -f swagger.yaml && go run main.go && redocly lint swagger.yaml` +. The generate command is defined as: `rm -f swagger.yaml && go run main.go && redocly lint swagger.yaml`. This command first removes any existing swagger.yaml file, then generates a new one, and finally lints it using Redocly.
Maintainability	Remove redundant information in the documentation. Replace the repeated information about installing Redocly with a reference to the earlier mention to avoid redundancy and improve document clarity. tyk-api-documentation/README.md [21] -1. Make sure that redocly is installed in your system. You can install Redocly from (https://github.com/Redocly/redocly-cli) +1. Make sure that Redocly is installed in your system. Refer to the installation guide above.

---

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

[sonarqubecloud[bot]]

Please retry analysis of this Pull-Request directly on SonarCloud

[github-actions[bot]]

:boom: CI tests failed :see_no_evil:

git-state

all ok

Please look at the run or in the Checks tab.

[github-actions[bot]]

:boom: CI tests failed :see_no_evil:

git-state

all ok

Please look at the run or in the Checks tab.

[sonarqubecloud[bot]]

Quality Gate passed

Issues
0 New issues
0 Accepted issues

Measures
0 Security Hotspots
No data about Coverage
0.0% Duplication on New Code

See analysis details on SonarCloud

[github-actions[bot]]

Swagger Changes

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

[sonarqubecloud[bot]]

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

[titpetric]

/release to release-5.6

[tykbot[bot]]

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

[tykbot[bot]]

@titpetric Succesfully merged PR

[titpetric]

/release to release-5.6.0

[tykbot[bot]]

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

[tykbot[bot]]

@titpetric Succesfully merged PR