[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>&nbsp; &nbsp; &nbsp; &nbsp;
</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>&nbsp;
&nbsp; </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)

.github/workflows/lint-swagger.yml

@@ -1,17 +1,103 @@
+# yamllint disable rule:line-length rule:truthy
+---
+name: "Lint swagger schema"
+
 on:
   pull_request:
-    branches:
-      - master
-      - release-**
+    paths:
+      - 'swagger.yml'
 
 jobs:
-  test_swagger_editor_validator_remote:
+  redocly_validator:
+    runs-on: ubuntu-latest
+    name: Validate the swagger with redocly cli
+
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 20
+      - name: Validate OpenAPI definition with redocly
+        run: |
+          npm install @redocly/cli -g
+          redocly lint swagger.yml --config=redocly.yml
+
+  diff_swagger:
+    name: Diff swagger yaml for comment
     runs-on: ubuntu-latest
-    name: Swagger Editor Validator Remote
 
     steps:
-      - uses: actions/checkout@v2
-      - name: Validate OpenAPI definition
-        uses: char0n/swagger-editor-validate@v1
+      - name: Use GitHub Token
+        env:
+          TOKEN: ${{ secrets.ORG_GH_TOKEN }}
+        run: >
+          git config --global url."https://${TOKEN}@github.com".insteadOf "https://github.com"
+
+      - name: Checkout repo
+        uses: TykTechnologies/github-actions/.github/actions/checkout-pr@main
+        with:
+          token: ${{ secrets.ORG_GH_TOKEN }}
+
+      - name: Setup Golang
+        uses: actions/setup-go@v5
+        with:
+          go-version: '1.22.x'
+
+      - name: Install dyff binary
+        run: |
+          # this is the upstream, missing -w (trim whitespace)
+          # curl --silent --location https://git.io/JYfAY | bash
+          git clone --depth=1 https://github.com/aoktox/dyff
+          cd dyff && go install ./cmd/...
+
+      - name: Set up comment author
+        run: |
+          git config --local user.email "github-actions[bot]@users.noreply.github.com"
+          git config --local user.name "github-actions[bot]"
+
+      - name: Collect
+        run: |
+          cp swagger.yml swagger-current.yml
+
+          git checkout -- .
+          git fetch --depth=1 origin ${{ github.base_ref }}
+          git checkout ${{ github.base_ref }}
+
+          cp swagger.yml swagger-prev.yml
+
+      - name: Diff
+        id: api-check
+        run: |
+          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
+
+          LINE_COUNT=$(wc -l < changes.txt)
+
+          echo "diff-output<<EOF" >> $GITHUB_OUTPUT
+          if [ $LINE_COUNT -gt 200 ]; then
+            echo "Changes in swagger.yml too large (line count ${LINE_COUNT}), check CI lint action for differences" >> $GITHUB_OUTPUT
+          else
+            cat changes.txt >> $GITHUB_OUTPUT
+          fi
+          echo "EOF" >> $GITHUB_OUTPUT
+
+      - name: Find Comment
+        uses: peter-evans/find-comment@v2
+        id: fc
+        with:
+          issue-number: ${{ github.event.pull_request.number }}
+          comment-author: 'github-actions[bot]'
+          body-includes: Swagger Changes
+
+      - name: Create or update comment
+        uses: peter-evans/create-or-update-comment@v3
         with:
-          definition-file: swagger.yml
+          comment-id: ${{ steps.fc.outputs.comment-id }}
+          issue-number: ${{ github.event.pull_request.number }}
+          body: |
+            Swagger Changes
+            ```diff
+            ${{ steps.api-check.outputs.diff-output || 'no api changes detected' }}
+            ```
+          edit-mode: replace

.redocly.lint-ignore.yaml

@@ -0,0 +1,42 @@
+# We have an external Swagger file that we use for Tyk OAs Endpoints this file ignores that external file
+# We have ambiguous-paths that would require to change the endpoint that the gateway level.
+#Those are also ignored (Currently only one of those exists)
+swagger.yml:
+  no-ambiguous-paths:
+    - '#/paths/~1tyk~1apis~1oas~1{apiID}'
+  no-invalid-media-type-examples:
+    - >-
+      #/paths/~1tyk~1apis~1oas/get/responses/200/content/application~1json/schema
+    - '#/paths/~1tyk~1apis~1oas/post/requestBody/content/application~1json/schema'
+    - >-
+      #/paths/~1tyk~1apis~1oas~1{apiID}/get/responses/200/content/application~1json/schema
+    - >-
+      #/paths/~1tyk~1apis~1oas~1{apiID}/put/requestBody/content/application~1json/schema
+    - >-
+      #/paths/~1tyk~1apis~1oas~1{apiID}/patch/requestBody/content/application~1json/schema
+    - >-
+      #/paths/~1tyk~1apis~1oas~1import/post/requestBody/content/application~1json/schema
+https://raw.githubusercontent.com/OAI/OpenAPI-Specification/main/schemas/v3.0/schema.json:
+  spec:
+    - '#/id'
+    - '#/$schema'
+    - '#/patternProperties'
+    - '#/definitions'
+    - '#/definitions/Info/patternProperties'
+    - '#/definitions/Contact/patternProperties'
+    - '#/definitions/License/patternProperties'
+    - '#/definitions/ExternalDocumentation/patternProperties'
+    - '#/definitions/Server/patternProperties'
+    - '#/definitions/ServerVariable/patternProperties'
+    - '#/definitions/Tag/patternProperties'
+    - '#/definitions/Paths/patternProperties'
+    - '#/definitions/Components/patternProperties'
+    - '#/definitions/Components/properties/schemas/patternProperties'
+    - '#/definitions/Components/properties/responses/patternProperties'
+    - '#/definitions/Components/properties/parameters/patternProperties'
+    - '#/definitions/Components/properties/examples/patternProperties'
+    - '#/definitions/Components/properties/requestBodies/patternProperties'
+    - '#/definitions/Components/properties/headers/patternProperties'
+    - '#/definitions/Components/properties/securitySchemes/patternProperties'
+    - '#/definitions/Components/properties/links/patternProperties'
+    - '#/definitions/Components/properties/callbacks/patternProperties'

docs/swagger.md

@@ -0,0 +1,34 @@
+# Tyk API Documentation
+
+The **Tyk API Documentation** is an OpenAPI specification that outlines the endpoints you can call on the gateway.
+
+## Notes
+
+The current OAS version is **v3.0.3**, generated from gateway **v5.6.0**.
+
+We are currently using OpenAPI Specification version **v3.0.3**.
+
+For linting the OAS, we use Redocly. You can install Redocly from [here](https://github.com/Redocly/redocly-cli).
+
+## How the OAS was generated
+
+We used the Go library [openapi-go](https://github.com/swaggest/openapi-go) because:
+1. It supports generating OAS for version **v3.0.3** (there are not many Go libraries that produce OAS v3.0.3).
+2. It is highly customizable, allowing you to define how each field is generated.
+3. It lets you write the generation code as functions, making it easier to read and maintain.
+
+## How to generate the Swagger.yml file
+
+1. Ensure that Redocly is installed on your system. You can install Redocly from [here](https://github.com/Redocly/redocly-cli).
+2. Clone the gateway repository and check out the branch [generate-swagger](https://github.com/TykTechnologies/tyk/tree/generate-swagger).
+3. Navigate to the directory [swagger/cmd](https://github.com/TykTechnologies/tyk/tree/generate-swagger/swagger/cmd). This directory contains a Makefile with a rule (`generate`) used to generate the swagger.yml file.
+4. Run the command `make generate` in this directory.
+5. After running this command, a `swagger.yml` file containing all the gateway endpoints will be generated in the same directory.
+6. What the `make generate` command does:
+      - The command is defined as: `rm -f swagger.yml && go run main.go && redocly lint swagger.yml`.
+      - It first removes the existing `swagger.yml` file (if any), generates a new `swagger.yml` file, and finally lints the file using Redocly.
+
+## File Structure
+
+1. In the Swagger folder, there is a file for each OAS tag (e.g., cache tag, key tag, etc.). If you want to add a new endpoint, add it to its specific tag.
+2. The `cmd` directory contains the `main.go` file (used to call all the generation functions), a Makefile, and the generated `swagger.yml` file.

redocly.yml

@@ -0,0 +1,56 @@
+rules:
+  #Special rules
+  no-unresolved-refs: error
+  no-unused-components: warn
+  security-defined: error
+  spec: error
+  spec-components-invalid-map-name: error #All the fixed fields declared below are objects that MUST use keys that match the regular expression
+  spec-strict-refs: error
+  #info
+  info-contact: warn
+  info-license: warn
+  info-license-url: warn
+  #Operations
+  operation-operationId: error
+  operation-operationId-unique: error
+  operation-operationId-url-safe: error
+  operation-summary: error
+  operation-2xx-response: error
+  operation-4xx-response: error
+  operation-description: error
+  #Parameters
+  no-invalid-parameter-examples:
+    severity: error
+    allowAdditionalProperties: false
+  operation-parameters-unique: error
+  #parameter-description: error    #uncomment this
+  path-declaration-must-exist: error
+  path-parameters-defined: error
+  #path rules
+  no-ambiguous-paths: error
+  no-http-verbs-in-paths:
+    severity: warn
+    splitIntoWords: true
+  no-identical-paths: error
+  no-path-trailing-slash: error
+
+  #Requests, Responses, and Schemas  rules
+  no-enum-type-mismatch: error
+  no-example-value-and-externalValue: error
+  no-invalid-media-type-examples:
+    severity: error
+    allowAdditionalProperties: false
+  #scalar-property-missing-example:
+    #severity: warn
+  no-invalid-schema-examples:
+    severity: error
+    allowAdditionalProperties: false
+  #Server rules
+  no-empty-servers: error
+  no-server-trailing-slash: error
+  no-undefined-server-variable: error
+  #Tags  rules
+  operation-singular-tag: error
+  #operation-tag-defined: error
+
+