[TT-13109]Generate New Swagger and Update Validator for Gateway #6231

Keithwachira · 2024-04-18T08:09:25Z

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 : #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

github-actions · 2024-04-18T08:10:10Z

API Changes

no api changes detected

github-actions · 2024-04-18T08:10:17Z

PR Description updated to latest commit (06a05b0)

github-actions · 2024-04-18T08:10:36Z

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 · 2024-04-18T08:11:23Z

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.

sonarcloud · 2024-04-18T08:53:12Z

Please retry analysis of this Pull-Request directly on SonarCloud

github-actions · 2024-04-19T12:15:38Z

💥 CI tests failed 🙈

git-state

all ok

Please look at the run or in the Checks tab.

github-actions · 2024-04-19T12:20:34Z

💥 CI tests failed 🙈

git-state

all ok

Please look at the run or in the Checks tab.

sonarcloud · 2024-04-29T04:32:44Z

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/workflows/redocly-swagger-lint.yml

tyk-api-documentation/README.md

## Description  ## Related Issue     ## Motivation and Context  ## How This Has Been Tested     ## Screenshots (if appropriate) ## Types of changes  - [ ] Bug fix (non-breaking change which fixes an issue) - [ ] New feature (non-breaking change which adds functionality) - [ ] Breaking change (fix or feature that would cause existing functionality to change) - [ ] Refactoring or add test (improvements in base code or adds test coverage to functionality) ## Checklist    - [ ] I ensured that the documentation is up to date - [ ] I explained why this PR updates go.mod in detail with reasoning why it's required - [ ] I would like a code coverage CI quality gate exception and have explained why

github-actions · 2024-09-17T13:23:11Z

Swagger Changes

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

titpetric · 2024-09-17T14:16:13Z

tyk-gateway-oas-generation-documentation/README.md

@@ -0,0 +1,34 @@
+# Tyk API Documentation


Hmmm, this needs a /docs addition. We currently don't have that folder, but, suggesting /docs/swagger.md at this point (we may change this in future as conventions get adjusted/considered).

Docs has some issues:

consistency (semver is vN.N.N, several v prefixes omitted)...

language, add it to it specific tag - maybe just re-read it or throw it through a grammar check :)

spacing (L5/headings should follow with an empty line like L1, 13, 20, 31)

fixed. I have also renamed the folder and the file

…Technologies/tyk into document-process-to-generate-the-oas

## Description  ## Related Issue     ## Motivation and Context  ## How This Has Been Tested     ## Screenshots (if appropriate) ## Types of changes  - [ ] Bug fix (non-breaking change which fixes an issue) - [ ] New feature (non-breaking change which adds functionality) - [ ] Breaking change (fix or feature that would cause existing functionality to change) - [ ] Refactoring or add test (improvements in base code or adds test coverage to functionality) ## Checklist    - [ ] I ensured that the documentation is up to date - [ ] I explained why this PR updates go.mod in detail with reasoning why it's required - [ ] I would like a code coverage CI quality gate exception and have explained why

…Technologies/tyk into document-process-to-generate-the-oas

…Technologies/tyk into document-process-to-generate-the-oas

sonarcloud · 2024-09-17T15:44:42Z

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

👏

titpetric · 2024-09-18T08:03:51Z

/release to release-5.6

tykbot · 2024-09-18T08:04:05Z

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

## **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** <table><thead><tr><th></th><th align="left">Relevant files</th></tr></thead><tbody><tr><td><strong>Documentation </strong></td><td><table> <tr> <td> <details> <summary><strong>README.md</strong><dd><code>Add Documentation for Generating Tyk API Swagger File</code>        </dd></summary> <hr> tyk-api-documentation/README.md <li>Introduced a new README.md for Tyk API Documentation.<br> <li> Detailed the process and tools used to generate the Open API <br>Specification (OAS).<br> <li> Provided step-by-step instructions on how to generate the Swagger.yml <br>file.<br> <li> Explained the file structure within the Swagger directory.<br> </details> </td> <td><a href="https://github.com/TykTechnologies/tyk/pull/6231/files#diff-25581cb9574ab0d44d58541ab1ead676194ddcb9dfe7ba4687197f9673df6093">+33/-0</a>    </td> </tr> </table></td></tr></tr></tbody></table> ___ > ✨ **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> (cherry picked from commit ec893f8)

tykbot · 2024-09-18T08:04:27Z

@titpetric Succesfully merged PR

…idator for Gateway (#6231) [TT-13109]Generate 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** <table><thead><tr><th></th><th align="left">Relevant files</th></tr></thead><tbody><tr><td><strong>Documentation </strong></td><td><table> <tr> <td> <details> <summary><strong>README.md</strong><dd><code>Add Documentation for Generating Tyk API Swagger File</code>        </dd></summary> <hr> tyk-api-documentation/README.md <li>Introduced a new README.md for Tyk API Documentation.<br> <li> Detailed the process and tools used to generate the Open API <br>Specification (OAS).<br> <li> Provided step-by-step instructions on how to generate the Swagger.yml <br>file.<br> <li> Explained the file structure within the Swagger directory.<br> </details> </td> <td><a href="https://github.com/TykTechnologies/tyk/pull/6231/files#diff-25581cb9574ab0d44d58541ab1ead676194ddcb9dfe7ba4687197f9673df6093">+33/-0</a>    </td> </tr> </table></td></tr></tr></tbody></table> ___ > ✨ **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>

titpetric · 2024-09-18T08:59:52Z

/release to release-5.6.0

tykbot · 2024-09-18T09:00:05Z

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

## **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** <table><thead><tr><th></th><th align="left">Relevant files</th></tr></thead><tbody><tr><td><strong>Documentation </strong></td><td><table> <tr> <td> <details> <summary><strong>README.md</strong><dd><code>Add Documentation for Generating Tyk API Swagger File</code>        </dd></summary> <hr> tyk-api-documentation/README.md <li>Introduced a new README.md for Tyk API Documentation.<br> <li> Detailed the process and tools used to generate the Open API <br>Specification (OAS).<br> <li> Provided step-by-step instructions on how to generate the Swagger.yml <br>file.<br> <li> Explained the file structure within the Swagger directory.<br> </details> </td> <td><a href="https://github.com/TykTechnologies/tyk/pull/6231/files#diff-25581cb9574ab0d44d58541ab1ead676194ddcb9dfe7ba4687197f9673df6093">+33/-0</a>    </td> </tr> </table></td></tr></tr></tbody></table> ___ > ✨ **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> (cherry picked from commit ec893f8)

tykbot · 2024-09-18T09:00:27Z

@titpetric Succesfully merged PR

…alidator for Gateway (#6231) [TT-13109]Generate 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** <table><thead><tr><th></th><th align="left">Relevant files</th></tr></thead><tbody><tr><td><strong>Documentation </strong></td><td><table> <tr> <td> <details> <summary><strong>README.md</strong><dd><code>Add Documentation for Generating Tyk API Swagger File</code>        </dd></summary> <hr> tyk-api-documentation/README.md <li>Introduced a new README.md for Tyk API Documentation.<br> <li> Detailed the process and tools used to generate the Open API <br>Specification (OAS).<br> <li> Provided step-by-step instructions on how to generate the Swagger.yml <br>file.<br> <li> Explained the file structure within the Swagger directory.<br> </details> </td> <td><a href="https://github.com/TykTechnologies/tyk/pull/6231/files#diff-25581cb9574ab0d44d58541ab1ead676194ddcb9dfe7ba4687197f9673df6093">+33/-0</a>    </td> </tr> </table></td></tr></tr></tbody></table> ___ > ✨ **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>

add documentaion for generating the swagger

06a05b0

github-actions bot added the Documentation label Apr 18, 2024

github-actions bot added the Review effort [1-5]: 2 label Apr 18, 2024

add the oas defination

153d0b0

change to h2 from h3

dc76322

Keithwachira changed the title ~~add documentation for generating the swagger~~ [DX-1272]add documentation for generating the swagger Apr 18, 2024

Update README.md

4717967

Keithwachira added 3 commits April 19, 2024 14:43

add github action to lint with redocly

ba2a4e2

test if document willl validate

e61b24a

change to push

c3240af

Keithwachira added 6 commits April 19, 2024 15:27

change to ubuntu latest

9c3c587

add node and redocly cli

acd0872

remove example requirement in scalar items

010a9f7

Update README.md

095f6ee

generate Oas array as an external reference instead of local object

1f03a5e

Merge branch 'master' into document-process-to-generate-the-oas

8628de2

Keithwachira added 4 commits August 5, 2024 11:54

Merge branch 'master' into document-process-to-generate-the-oas

53b401c

Merge branch 'master' into document-process-to-generate-the-oas

6bc4b1b

add example to swagger file and rename swagger

f21d9aa

Update README.md

1a175ff

letzya reviewed Aug 16, 2024

View reviewed changes

.github/workflows/redocly-swagger-lint.yml Outdated Show resolved Hide resolved

letzya reviewed Aug 16, 2024

View reviewed changes

tyk-api-documentation/README.md Outdated Show resolved Hide resolved

Keithwachira changed the title ~~[DX-1272]add documentation for generating the swagger~~ [TT-13109]add documentation for generating the swagger Sep 17, 2024

Keithwachira added 2 commits September 17, 2024 16:20

remove multiple clis and leave only one

c4a7def

Keithwachira changed the title ~~[TT-13109]add documentation for generating the swagger~~ [TT-13109]Generate New Swagger and Update Validator for Gateway Sep 17, 2024

remove multiple clis and leave only one (#6533)

89b1a00

titpetric reviewed Sep 17, 2024

View reviewed changes

Keithwachira added 7 commits September 17, 2024 18:06

Merge branch 'document-process-to-generate-the-oas' of github.com:Tyk…

6194397

…Technologies/tyk into document-process-to-generate-the-oas

Merge branch 'document-process-to-generate-the-oas' of github.com:Tyk…

b4746a6

…Technologies/tyk into document-process-to-generate-the-oas

Fix grammar in docs file (#6537)

cbd6d3b

Update swagger.md

0b3b319

Merge branch 'document-process-to-generate-the-oas' of github.com:Tyk…

578bd9c

…Technologies/tyk into document-process-to-generate-the-oas

change yaml to yml

d2b7d9e

titpetric approved these changes Sep 18, 2024

View reviewed changes

titpetric merged commit ec893f8 into master Sep 18, 2024
28 checks passed

titpetric deleted the document-process-to-generate-the-oas branch September 18, 2024 08:03

buger mentioned this pull request Sep 18, 2024

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

Merged

buger mentioned this pull request Sep 18, 2024

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

Merged

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

[TT-13109]Generate New Swagger and Update Validator for Gateway #6231

[TT-13109]Generate New Swagger and Update Validator for Gateway #6231

Keithwachira commented Apr 18, 2024 •

edited by jira bot

Loading

github-actions bot commented Apr 18, 2024 •

edited

Loading

github-actions bot commented Apr 18, 2024

github-actions bot commented Apr 18, 2024

github-actions bot commented Apr 18, 2024

sonarcloud bot commented Apr 18, 2024

github-actions bot commented Apr 19, 2024

github-actions bot commented Apr 19, 2024

sonarcloud bot commented Apr 29, 2024

github-actions bot commented Sep 17, 2024

titpetric Sep 17, 2024

Keithwachira Sep 17, 2024

sonarcloud bot commented Sep 17, 2024

titpetric left a comment

titpetric commented Sep 18, 2024

tykbot bot commented Sep 18, 2024

tykbot bot commented Sep 18, 2024

titpetric commented Sep 18, 2024

tykbot bot commented Sep 18, 2024

tykbot bot commented Sep 18, 2024

[TT-13109]Generate New Swagger and Update Validator for Gateway #6231

[TT-13109]Generate New Swagger and Update Validator for Gateway #6231

Conversation

Keithwachira commented Apr 18, 2024 • edited by jira bot Loading

User description

Type

Description

Changes walkthrough

github-actions bot commented Apr 18, 2024 • edited Loading

github-actions bot commented Apr 18, 2024

github-actions bot commented Apr 18, 2024

PR Review

github-actions bot commented Apr 18, 2024

PR Code Suggestions

sonarcloud bot commented Apr 18, 2024

github-actions bot commented Apr 19, 2024

💥 CI tests failed 🙈

git-state

github-actions bot commented Apr 19, 2024

💥 CI tests failed 🙈

git-state

sonarcloud bot commented Apr 29, 2024

Quality Gate passed

github-actions bot commented Sep 17, 2024

titpetric Sep 17, 2024

Choose a reason for hiding this comment

Keithwachira Sep 17, 2024

Choose a reason for hiding this comment

sonarcloud bot commented Sep 17, 2024

Quality Gate passed

titpetric left a comment

Choose a reason for hiding this comment

titpetric commented Sep 18, 2024

tykbot bot commented Sep 18, 2024

tykbot bot commented Sep 18, 2024

titpetric commented Sep 18, 2024

tykbot bot commented Sep 18, 2024

tykbot bot commented Sep 18, 2024

Keithwachira commented Apr 18, 2024 •

edited by jira bot

Loading

github-actions bot commented Apr 18, 2024 •

edited

Loading