Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

[TT-13742] Update documentation for master #5840

Merged
merged 1 commit into from
Dec 31, 2024

Conversation

buger
Copy link
Member

@buger buger commented Dec 20, 2024

Triggered by: lghiur

Included:

Tyk Gateway: true
Tyk Dashboard: true
Tyk MDCB false
Tyk Pump false

Intended for: master
Changes sourced from: release-5.7.1
Config info generator branch: main

Note: 5.7.1 docs updates (branch suffix: docs)

JIRA: https://tyktech.atlassian.net/browse/TT-13742

Copy link
Contributor

PR Reviewer Guide 🔍

Here are some key observations to aid the review process:

⏱️ Estimated effort to review: 2 🔵🔵⚪⚪⚪
🧪 No relevant tests
🔒 No security concerns identified
⚡ Recommended focus areas for review

Schema Reference Update

The schema references have been updated to point to the OpenAPI Specification's main schema. Ensure that this change aligns with the intended functionality and does not break compatibility with existing configurations or tools.

              examples:
                oasExampleList:
                  $ref: '#/components/examples/oasExampleList'
              schema:
                items:
                  allOf:
                  - $ref: https://raw.githubusercontent.com/OAI/OpenAPI-Specification/main/schemas/v3.0/schema.json
                  - $ref: '#/components/schemas/XTykAPIGateway'
                type: array
          description: List of API definitions in Tyk OAS format.
        "403":
          content:
            application/json:
              example:
                message: Attempted administrative access with invalid or missing key!
                status: error
              schema:
                $ref: '#/components/schemas/ApiStatusMessage'
          description: Forbidden
      summary: List all APIs in Tyk OAS API format.
      tags:
      - Tyk OAS APIs
    post:
      description: Create an API with Tyk OAS API format on the Tyk Gateway.
      operationId: createApiOAS
      parameters:
      - description: The base API which the new version will be linked to.
        example: 663a4ed9b6be920001b191ae
        in: query
        name: base_api_id
        required: false
        schema:
          type: string
      - description: The version name of the base API while creating the first version.
          This doesn't have to be sent for the next versions but if it is set, it
          will override base API version name.
        example: Default
        in: query
        name: base_api_version_name
        required: false
        schema:
          type: string
      - description: The version name of the created version.
        example: v2
        in: query
        name: new_version_name
        required: false
        schema:
          type: string
      - description: If true, the new version is set as default version.
        example: true
        in: query
        name: set_default
        required: false
        schema:
          type: boolean
      requestBody:
        content:
          application/json:
            example:
              components:
                securitySchemes:
                  bearerAuth:
                    description: The API Access Credentials
                    scheme: bearer
                    type: http
              info:
                description: This is a sample OAS.
                title: OAS Sample
                version: 1.0.0
              openapi: 3.0.3
              paths:
                /api/sample/users:
                  get:
                    operationId: getUsers
                    responses:
                      "200":
                        content:
                          application/json:
                            schema:
                              items:
                                properties:
                                  name:
                                    type: string
                                type: object
                              type: array
                        description: fetched users
                    summary: Get users
                    tags:
                    - users
              security:
              - bearerAuth: []
              servers:
              - url: https://localhost:8080
              x-tyk-api-gateway:
                info:
                  name: user
                  state:
                    active: true
                server:
                  listenPath:
                    strip: true
                    value: /user-test/
                upstream:
                  url: https://localhost:8080
            schema:
              allOf:
              - $ref: https://raw.githubusercontent.com/OAI/OpenAPI-Specification/main/schemas/v3.0/schema.json
              - $ref: '#/components/schemas/XTykAPIGateway'
      responses:
        "200":
          content:
            application/json:
              example:
                action: added
                key: e30bee13ad4248c3b529a4c58bb7be4e
                status: ok
              schema:
                $ref: '#/components/schemas/ApiModifyKeySuccess'
          description: API created.
        "400":
          content:
            application/json:
              example:
                message: the payload should contain x-tyk-api-gateway
                status: error
              schema:
                $ref: '#/components/schemas/ApiStatusMessage'
          description: Bad Request
        "403":
          content:
            application/json:
              example:
                message: Attempted administrative access with invalid or missing key!
                status: error
              schema:
                $ref: '#/components/schemas/ApiStatusMessage'
          description: Forbidden
        "500":
          content:
            application/json:
              example:
                message: file object creation failed, write error
                status: error
              schema:
                $ref: '#/components/schemas/ApiStatusMessage'
          description: Internal server error.
      summary: Create an API with Tyk OAS format.
      tags:
      - Tyk OAS APIs
  /tyk/apis/oas/{apiID}:
    delete:
      description: Deleting an API definition will remove the file from the file store,
        the API definition will not be unloaded, a separate reload request will need
        to be made to disable the API endpoint.
      operationId: deleteOASApi
      parameters:
      - description: The API ID.
        example: 1bd5c61b0e694082902cf15ddcc9e6a7
        in: path
        name: apiID
        required: true
        schema:
          type: string
      responses:
        "200":
          content:
            application/json:
              example:
                action: deleted
                key: 1bd5c61b0e694082902cf15ddcc9e6a7
                status: ok
              schema:
                $ref: '#/components/schemas/ApiModifyKeySuccess'
          description: API deleted
        "400":
          content:
            application/json:
              example:
                message: Must specify an apiID to delete
                status: error
              schema:
                $ref: '#/components/schemas/ApiStatusMessage'
          description: Bad Request
        "403":
          content:
            application/json:
              example:
                message: Attempted administrative access with invalid or missing key!
                status: error
              schema:
                $ref: '#/components/schemas/ApiStatusMessage'
          description: Forbidden
        "404":
          content:
            application/json:
              example:
                message: API not found
                status: error
              schema:
                $ref: '#/components/schemas/ApiStatusMessage'
          description: API not found.
        "500":
          content:
            application/json:
              example:
                message: Delete failed
                status: error
              schema:
                $ref: '#/components/schemas/ApiStatusMessage'
          description: Internal server error.
      summary: Deleting a Tyk OAS API.
      tags:
      - Tyk OAS APIs
    get:
      description: Get Tyk OAS API definition using an API ID.
      operationId: getOASApi
      parameters:
      - description: "By default mode is empty which means it will return the Tyk
          API OAS spec including the x-tyk-api-gateway part. \n When mode=public,
          the Tyk OAS API spec will exclude the x-tyk-api-gateway part in the response."
        example: public
        in: query
        name: mode
        required: false
        schema:
          enum:
          - public
          type: string
      - description: ID of the API you want to fetch
        example: 4c1c0d8fc885401053ddac4e39ef676b
        in: path
        name: apiID
        required: true
        schema:
          type: string
      responses:
        "200":
          content:
            application/json:
              examples:
                oasExample:
                  $ref: '#/components/examples/oasExample'
              schema:
                allOf:
                - $ref: https://raw.githubusercontent.com/OAI/OpenAPI-Specification/main/schemas/v3.0/schema.json
                - $ref: '#/components/schemas/XTykAPIGateway'
          description: OK
          headers:
            x-tyk-base-api-id:
              description: ID of the base API if the requested API is a version.
              schema:
                type: string
              style: simple
        "400":
          content:
            application/json:
              example:
                message: the requested API definition is in Tyk classic format, please
                  use old API endpoint
                status: error
              schema:
                $ref: '#/components/schemas/ApiStatusMessage'
          description: Bad Request
        "403":
          content:
            application/json:
              example:
                message: Attempted administrative access with invalid or missing key!
                status: error
              schema:
                $ref: '#/components/schemas/ApiStatusMessage'
          description: Forbidden
        "404":
          content:
            application/json:
              example:
                message: API not found
                status: error
              schema:
                $ref: '#/components/schemas/ApiStatusMessage'
          description: API not found.
      summary: Get a Tyk OAS API definition.
      tags:
      - Tyk OAS APIs
    patch:
      description: |-
        You can use this endpoint to update Tyk OAS part of the Tyk API definition.
        This endpoint allows you to configure Tyk OAS extension based on query params provided(similar to import).
      operationId: patchApiOAS
      parameters:
      - description: ID of the API you want to fetch.
        example: 4c1c0d8fc885401053ddac4e39ef676b
        in: path
        name: apiID
        required: true
        schema:
          type: string
      - $ref: '#/components/parameters/UpstreamURL'
      - $ref: '#/components/parameters/ListenPath'
      - $ref: '#/components/parameters/CustomDomain'
      - $ref: '#/components/parameters/AllowList'
      - $ref: '#/components/parameters/ValidateRequest'
      - $ref: '#/components/parameters/MockResponse'
      - $ref: '#/components/parameters/Authentication'
      requestBody:
        content:
          application/json:
            example:
              components:
                securitySchemes:
                  bearerAuth:
                    description: The API Access Credentials
                    scheme: bearer
                    type: http
              info:
                description: This is a sample OAS.
                title: OAS Sample
                version: 1.0.0
              openapi: 3.0.3
              paths:
                /api/sample/users:
                  get:
                    operationId: getUsers
                    responses:
                      "200":
                        content:
                          application/json:
                            schema:
                              items:
                                properties:
                                  name:
                                    type: string
                                type: object
                              type: array
                        description: fetched users
                    summary: Get users
                    tags:
                    - users
              security:
              - bearerAuth: []
              servers:
              - url: https://localhost:8080
              x-tyk-api-gateway:
                info:
                  name: user
                  state:
                    active: true
                server:
                  listenPath:
                    strip: true
                    value: /user-test/
                upstream:
                  url: https://localhost:8080
            schema:
              $ref: https://raw.githubusercontent.com/OAI/OpenAPI-Specification/main/schemas/v3.0/schema.json
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiModifyKeySuccess'
          description: API patched.
        "400":
          content:
            application/json:
              example:
                message: Must specify an apiID to patch
                status: error
              schema:
                $ref: '#/components/schemas/ApiStatusMessage'
          description: Bad Request
        "403":
          content:
            application/json:
              example:
                message: Attempted administrative access with invalid or missing key!
                status: error
              schema:
                $ref: '#/components/schemas/ApiStatusMessage'
          description: Forbidden
        "404":
          content:
            application/json:
              example:
                message: API not found
                status: error
              schema:
                $ref: '#/components/schemas/ApiStatusMessage'
          description: API not found.
        "500":
          content:
            application/json:
              example:
                message: file object creation failed, write error
                status: error
              schema:
                $ref: '#/components/schemas/ApiStatusMessage'
          description: Internal server error.
      summary: Patch API in Tyk OAS format.
      tags:
      - Tyk OAS APIs
    put:
      description: |-
        Updating an API definition uses the same signature an object as a `POST`, however it will first ensure that the API ID that is being updated is the same as the one in the object being `PUT`.


              Updating will completely replace the file descriptor and will not change an API Definition that has already been loaded, the hot-reload endpoint will need to be called to push the new definition to live.
      operationId: updateApiOAS
      parameters:
      - description: ID of the API you want to fetch
        example: 4c1c0d8fc885401053ddac4e39ef676b
        in: path
        name: apiID
        required: true
        schema:
          type: string
      requestBody:
        content:
          application/json:
            example:
              components:
                securitySchemes:
                  bearerAuth:
                    description: The API Access Credentials
                    scheme: bearer
                    type: http
              info:
                description: This is a sample OAS.
                title: OAS Sample
                version: 1.0.0
              openapi: 3.0.3
              paths:
                /api/sample/users:
                  get:
                    operationId: getUsers
                    responses:
                      "200":
                        content:
                          application/json:
                            schema:
                              items:
                                properties:
                                  name:
                                    type: string
                                type: object
                              type: array
                        description: fetched users
                    summary: Get users
                    tags:
                    - users
              security:
              - bearerAuth: []
              servers:
              - url: https://localhost:8080
              x-tyk-api-gateway:
                info:
                  name: user
                  state:
                    active: true
                server:
                  listenPath:
                    strip: true
                    value: /user-test/
                upstream:
                  url: https://localhost:8080
            schema:
              allOf:
              - $ref: https://raw.githubusercontent.com/OAI/OpenAPI-Specification/main/schemas/v3.0/schema.json
              - $ref: '#/components/schemas/XTykAPIGateway'
      responses:
        "200":
          content:
            application/json:
              example:
                action: modified
                key: e30bee13ad4248c3b529a4c58bb7be4e
                status: ok
              schema:
                $ref: '#/components/schemas/ApiModifyKeySuccess'
          description: API updated
        "400":
          content:
            application/json:
              example:
                message: Request APIID does not match that in Definition! For Update
                  operations these must match.
                status: error
              schema:
                $ref: '#/components/schemas/ApiStatusMessage'
          description: Bad Request
        "403":
          content:
            application/json:
              example:
                message: Attempted administrative access with invalid or missing key!
                status: error
              schema:
                $ref: '#/components/schemas/ApiStatusMessage'
          description: Forbidden
        "404":
          content:
            application/json:
              example:
                message: API not found
                status: error
              schema:
                $ref: '#/components/schemas/ApiStatusMessage'
          description: API not found
        "500":
          content:
            application/json:
              example:
                message: file object creation failed, write error
                status: error
              schema:
                $ref: '#/components/schemas/ApiStatusMessage'
          description: Internal server error.
      summary: Update a Tyk OAS API definition.
      tags:
      - Tyk OAS APIs
  /tyk/apis/oas/{apiID}/export:
    get:
      description: Use the mode query parameter to specify if you want the x-tyk-api-gateway
        stripped out.
      operationId: downloadApiOASPublic
      parameters:
      - description: ID of the API you want to fetch.
        example: 4c1c0d8fc885401053ddac4e39ef676b
        in: path
        name: apiID
        required: true
        schema:
          type: string
      - description: "By default mode is empty which means it will return the Tyk
          API OAS spec including the x-tyk-api-gateway part. \n When mode=public,
          the Tyk OAS API spec will exclude the x-tyk-api-gateway part in the response."
        example: public
        in: query
        name: mode
        required: false
        schema:
          enum:
          - public
          type: string
      responses:
        "200":
          content:
            application/octet-stream:
              schema:
                format: binary
                type: string
          description: Exported API definition file
        "400":
          content:
            application/json:
              example:
                message: requesting API definition that is in Tyk classic format
                status: error
              schema:
                $ref: '#/components/schemas/ApiStatusMessage'
          description: Bad Request
        "403":
          content:
            application/json:
              example:
                message: Attempted administrative access with invalid or missing key!
                status: error
              schema:
                $ref: '#/components/schemas/ApiStatusMessage'
          description: Forbidden
        "404":
          content:
            application/json:
              example:
                message: API not found
                status: error
              schema:
                $ref: '#/components/schemas/ApiStatusMessage'
          description: Not Found
        "500":
          content:
            application/json:
              example:
                message: Unexpected error
                status: error
              schema:
                $ref: '#/components/schemas/ApiStatusMessage'
          description: Internal server error.
      summary: Download a Tyk OAS format API.
      tags:
      - Tyk OAS APIs
  /tyk/apis/oas/{apiID}/versions:
    get:
      description: Listing versions of a Tyk OAS API.
      operationId: listOASApiVersions
      parameters:
      - description: ID of the API you want to fetch.
        example: 4c1c0d8fc885401053ddac4e39ef676b
        in: path
        name: apiID
        required: true
        schema:
          type: string
      - $ref: '#/components/parameters/SearchText'
      - $ref: '#/components/parameters/AccessType'
      responses:
        "200":
          content:
            application/json:
              example:
                apis:
                - expirationDate: ""
                  id: keyless
                  internal: false
                  isDefaultVersion: false
                  name: Tyk Test Keyless API
                  versionName: ""
                - expirationDate: ""
                  id: 1f20d5d2731d47ac9c79fddf826eda00
                  internal: false
                  isDefaultVersion: true
                  name: Version three Api
                  versionName: v2
                status: success
              schema:
                $ref: '#/components/schemas/VersionMetas'
          description: API version metas.
        "403":
          content:
            application/json:
              example:
                message: Attempted administrative access with invalid or missing key!
                status: error
              schema:
                $ref: '#/components/schemas/ApiStatusMessage'
          description: Forbidden
        "404":
          content:
            application/json:
              example:
                message: API not found.
                status: error
              schema:
                $ref: '#/components/schemas/ApiStatusMessage'
          description: API not found
      summary: Listing versions of a Tyk OAS API.
      tags:
      - Tyk OAS APIs
  /tyk/apis/oas/export:
    get:
      description: Download all Tyk OAS format APIs, from the Gateway.
      operationId: downloadApisOASPublic
      parameters:
      - description: "By default mode is empty which means it will return the Tyk
          API OAS spec including the x-tyk-api-gateway part. \n When mode=public,
          the Tyk OAS API spec will exclude the x-tyk-api-gateway part in the response."
        example: public
        in: query
        name: mode
        required: false
        schema:
          enum:
          - public
          type: string
      responses:
        "200":
          content:
            application/octet-stream:
              schema:
                format: binary
                type: string
          description: Get a list of Tyk OAS APIs definitions.
        "403":
          content:
            application/json:
              example:
                message: Attempted administrative access with invalid or missing key!
                status: error
              schema:
                $ref: '#/components/schemas/ApiStatusMessage'
          description: Forbidden
        "500":
          content:
            application/json:
              example:
                message: Unexpected error
                status: error
              schema:
                $ref: '#/components/schemas/ApiStatusMessage'
          description: Internal server error.
      summary: Download all Tyk OAS format APIs.
      tags:
      - Tyk OAS APIs
  /tyk/apis/oas/import:
    post:
      description: |-
        Import an Tyk OAS format API without x-tyk-gateway.
         For use with an existing Tyk OAS API that you want to expose via your Tyk Gateway.
      operationId: importOAS
      parameters:
      - $ref: '#/components/parameters/UpstreamURL'
      - $ref: '#/components/parameters/ListenPath'
      - $ref: '#/components/parameters/CustomDomain'
      - $ref: '#/components/parameters/AllowList'
      - $ref: '#/components/parameters/ValidateRequest'
      - $ref: '#/components/parameters/MockResponse'
      - $ref: '#/components/parameters/Authentication'
      - description: The base API which the new version will be linked to.
        example: 663a4ed9b6be920001b191ae
        in: query
        name: base_api_id
        required: false
        schema:
          type: string
      - description: The version name of the base API while creating the first version.
          This doesn't have to be sent for the next versions but if it is set, it
          will override base API version name.
        example: Default
        in: query
        name: base_api_version_name
        required: false
        schema:
          type: string
      - description: The version name of the created version.
        example: v2
        in: query
        name: new_version_name
        required: false
        schema:
          type: string
      - description: If true, the new version is set as default version.
        example: true
        in: query
        name: set_default
        required: false
        schema:
          type: boolean
      requestBody:
        content:
          application/json:
            example:
              components:
                securitySchemes:
                  bearerAuth:
                    description: The API Access Credentials
                    scheme: bearer
                    type: http
              info:
                description: This is a sample OAS.
                title: OAS Sample
                version: 1.0.0
              openapi: 3.0.3
              paths:
                /api/sample/users:
                  get:
                    operationId: getUsers
                    responses:
                      "200":
                        content:
                          application/json:
                            schema:
                              items:
                                properties:
                                  name:
                                    type: string
                                type: object
                              type: array
                        description: fetched users
                    summary: Get users
                    tags:
                    - users
              security:
              - bearerAuth: []
              servers:
              - url: https://localhost:8080
            schema:
              $ref: https://raw.githubusercontent.com/OAI/OpenAPI-Specification/main/schemas/v3.0/schema.json
      responses:
New Security Configurations

Two new security options (security.forbid_admin_view_access_token and security.forbid_admin_reset_access_token) have been added. Verify that these options are documented correctly and that their default behavior is consistent with expectations.

### security.forbid_admin_view_access_token
ENV: <b>TYK_DB_SECURITY_FORBIDADMINVIEWACCESSTOKEN</b><br />
Type: `bool`<br />

ForbidAdminViewAccessToken is a security feature that allows you to prevent the admin user from viewing the access token of a user. The default is false.

### security.forbid_admin_reset_access_token
ENV: <b>TYK_DB_SECURITY_FORBIDADMINRESETACCESSTOKEN</b><br />
Type: `bool`<br />

ForbidAdminResetAccessToken is a security feature that allows you to prevent the admin user from resetting the access token of a user. The default is false.
Management Node Clarification

The management_node configuration has been clarified for pro installations. Confirm that this change is accurate and does not introduce ambiguity for other environments.

For pro installations, `management_node` is not a valid configuration option.
Always set `management_node` to `false` in pro environments.

Copy link
Contributor

PR Code Suggestions ✨

Explore these optional code suggestions:

CategorySuggestion                                                                                                                                    Score
General
Validate the accessibility of external schema references to prevent validation errors

Ensure that the new $ref URLs pointing to the OpenAPI schema (e.g.,
https://raw.githubusercontent.com/OAI/OpenAPI-Specification/main/schemas/v3.0/schema.json)
are valid and accessible, as broken references could lead to schema validation
issues.

tyk-docs/assets/others/gateway-swagger.yml [566]

+- $ref: https://raw.githubusercontent.com/OAI/OpenAPI-Specification/main/schemas/v3.0/schema.json
 
-
Suggestion importance[1-10]: 7

Why: Ensuring the accessibility of external schema references is crucial to prevent validation issues during schema parsing. While the suggestion is valid, it is not actionable within the PR itself and requires external verification, slightly reducing its score.

7
Clarify the impact of configuration changes for management_node in pro environments

Clarify the implications of setting management_node to false in pro environments,
ensuring users understand its impact on system behavior and configuration.

tyk-docs/content/shared/gateway-config.md [728-729]

+For pro installations, `management_node` is not a valid configuration option.
+Always set `management_node` to `false` in pro environments.
 
-
Suggestion importance[1-10]: 5

Why: Clarifying the implications of setting management_node to false in pro environments could improve user understanding and documentation quality. However, the suggestion does not propose a specific change to the PR content, which limits its impact.

5
Security
Confirm the proper implementation of new security configurations to ensure they function as intended

Verify that the new security configurations security.forbid_admin_view_access_token
and security.forbid_admin_reset_access_token are correctly implemented and enforced
in the system to avoid potential security loopholes.

tyk-docs/content/shared/dashboard-config.md [845-851]

+ForbidAdminViewAccessToken is a security feature that allows you to prevent the admin user from viewing the access token of a user. The default is false.
 
+ForbidAdminResetAccessToken is a security feature that allows you to prevent the admin user from resetting the access token of a user. The default is false.
Suggestion importance[1-10]: 6

Why: Verifying the implementation of new security configurations is important to avoid potential security loopholes. However, the suggestion is not directly actionable within the PR and requires external validation, which slightly reduces its score.

6

Copy link

netlify bot commented Dec 20, 2024

PS. Pls add /docs/nightly to the end of url

Name Link
🔨 Latest commit df737bb
🔍 Latest deploy log https://app.netlify.com/sites/tyk-docs/deploys/6767d2a688a8ad00082e8335
😎 Deploy Preview https://deploy-preview-5840--tyk-docs.netlify.app
📱 Preview on mobile
Toggle QR Code...

QR Code

Use your smartphone camera to open QR code link.

To edit notification comments on pull requests, go to your Netlify site configuration.

@buger buger force-pushed the update/TT-13742/release-master-docs branch from 96ec839 to df737bb Compare December 22, 2024 08:49
@sharadregoti sharadregoti merged commit 8e2fc71 into master Dec 31, 2024
9 checks passed
@sharadregoti sharadregoti deleted the update/TT-13742/release-master-docs branch December 31, 2024 05:15
@sharadregoti
Copy link
Contributor

/release to release-5.7.1

Copy link

tykbot bot commented Dec 31, 2024

@sharadregoti Release branch not found

@sharadregoti
Copy link
Contributor

/release to release-5.7

Copy link

tykbot bot commented Dec 31, 2024

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

Copy link

tykbot bot commented Dec 31, 2024

@sharadregoti Succesfully merged PR

buger added a commit that referenced this pull request Dec 31, 2024
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Projects
None yet
Development

Successfully merging this pull request may close these issues.

3 participants