search

TykTechnologies / tyk

Tyk Open Source API Gateway written in Go, supporting REST, GraphQL, TCP and gRPC protocols
Other
9.51k stars 1.07k forks source link

[TT-12635] Update swagger.yml with ExtendedPathsSet.RateLimitMeta #6417

Closed titpetric closed 1 month ago

titpetric commented 1 month ago

User description

https://tyktech.atlassian.net/browse/TT-12635

PR Type

enhancement, documentation

Description

Changes walkthrough 📝

Relevant files
Enhancement
swagger.yml
Add RateLimitMeta and update API version                                 
swagger.yml
  • Updated API version from 5.4.0 to 5.5.0
  • Added RateLimitMeta object definition
  • Included rate_limit property in ExtendedPathsSet
    		•  +28/-1   

    💡 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 1 month ago

    PR Reviewer Guide 🔍

    ⏱️ Estimated effort to review: 2 🔵🔵⚪⚪⚪
    🧪 No relevant tests
    🔒 No security concerns identified
    ⚡ No key issues to review
    github-actions[bot] commented 1 month ago

    API Changes

    no api changes detected
    github-actions[bot] commented 1 month ago

    PR Code Suggestions ✨

    CategorySuggestion                                                                                                                                    Score
    Enhancement
    Add examples to the properties in 'RateLimitMeta' to illustrate their usage ___ **Adding examples for the properties within RateLimitMeta can greatly enhance
    understanding and provide clear usage scenarios to API consumers. This is especially
    useful in complex configurations.** [swagger.yml [2616-2635]](https://github.com/TykTechnologies/tyk/pull/6417/files#diff-8f3c4cb253eee09ae2401daa7279a8bbfbfd4168bb579c3ac0ee5c672d63bb2cR2616-R2635) ```diff RateLimitMeta: properties: disabled: type: boolean + example: false x-go-name: Disabled method: type: string + example: "GET" x-go-name: Method path: type: string + example: "/api/data" x-go-name: Path per: type: number format: double + example: 100 x-go-name: Per rate: type: number format: double + example: 1000 x-go-name: Rate title: RateLimitMeta configures rate limits per API path. type: object x-go-package: github.com/TykTechnologies/tyk/apidef ```
    Suggestion importance[1-10]: 9 Why: Adding examples significantly enhances understanding and provides clear usage scenarios, which is especially useful for API consumers dealing with complex configurations.
    		9
    Add a description to the 'rate_limit' property for better clarity ___ **It's recommended to add a description for the rate_limit property to clarify its
    purpose and usage within the API schema. This will help developers understand the
    context and functionality of this property.** [swagger.yml [2685-2689]](https://github.com/TykTechnologies/tyk/pull/6417/files#diff-8f3c4cb253eee09ae2401daa7279a8bbfbfd4168bb579c3ac0ee5c672d63bb2cR2685-R2689) ```diff rate_limit: type: array items: $ref: '#/components/schemas/RateLimitMeta' x-go-name: RateLimit + description: "Defines the rate limits applicable to specific API methods or paths." ```
    Suggestion importance[1-10]: 8 Why: Adding a description to the 'rate_limit' property improves the documentation and helps developers understand its purpose and usage, enhancing the overall clarity of the API schema.
    		8
    Best practice
    Specify default values for 'disabled', 'method', and 'path' in 'RateLimitMeta' ___ **Consider specifying the default values for the disabled, method, and path properties
    in the RateLimitMeta schema. Default values can provide a fallback and clarify
    expected behavior when these properties are not explicitly set by the user.** [swagger.yml [2618-2625]](https://github.com/TykTechnologies/tyk/pull/6417/files#diff-8f3c4cb253eee09ae2401daa7279a8bbfbfd4168bb579c3ac0ee5c672d63bb2cR2618-R2625) ```diff disabled: type: boolean + default: false x-go-name: Disabled method: type: string + default: "GET" x-go-name: Method path: type: string + default: "/" x-go-name: Path ```
    Suggestion importance[1-10]: 7 Why: Specifying default values for these properties provides a fallback and clarifies expected behavior when they are not explicitly set, improving usability and reducing potential errors.
    		7
    Possible issue
    Change the type from 'double' to 'integer' for 'per' and 'rate' if only whole numbers are required ___ **To ensure consistency in the representation of numeric values, consider using
    integer type with a specific format for the per and rate properties if these values
    are expected to be whole numbers. Using double might be unnecessary if fractional
    values are not required.** [swagger.yml [2627-2634]](https://github.com/TykTechnologies/tyk/pull/6417/files#diff-8f3c4cb253eee09ae2401daa7279a8bbfbfd4168bb579c3ac0ee5c672d63bb2cR2627-R2634) ```diff per: - type: number - format: double + type: integer + format: int64 x-go-name: Per rate: - type: number - format: double - x-go-Name: Rate + type: integer + format: int64 + x-go-name: Rate ```
    Suggestion importance[1-10]: 6 Why: Changing the type to 'integer' ensures consistency if only whole numbers are expected, but this suggestion should be validated against actual requirements to avoid unnecessary changes.
    		6
    sonarcloud[bot] commented 1 month ago

    Quality Gate Passed 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