From 2397d0876bda76329393d1a02fe6d9721dc26d47 Mon Sep 17 00:00:00 2001 From: Kevsy Date: Fri, 7 Jun 2024 13:01:03 +0100 Subject: [PATCH 1/4] x-correlator fix issue 8 --- .../simple-edge-discovery.yaml | 56 +++++++++---------- 1 file changed, 28 insertions(+), 28 deletions(-) diff --git a/code/API_definitions/simple-edge-discovery.yaml b/code/API_definitions/simple-edge-discovery.yaml index 9b68d87..4f95432 100644 --- a/code/API_definitions/simple-edge-discovery.yaml +++ b/code/API_definitions/simple-edge-discovery.yaml @@ -246,14 +246,14 @@ paths: schema: $ref: "#/components/schemas/PhoneNumber" - - name: X-Correlator + - name: x-correlator in: header required: false description: | - When the API Consumer includes the "X-Correlator" header in the + When the API Consumer includes the "x-correlator" header in the request, the API provider must include it in the response with the same value that was used in the request. Otherwise, it is - optional to include the "X-Correlator" header in the response with + optional to include the "x-correlator" header in the response with any valid value. Recommendation is to use UUID for values. schema: type: string @@ -308,12 +308,12 @@ components: openIdConnectUrl: .well-known/openid-configuration headers: - X-Correlator: + x-correlator: description: | - When the API Consumer includes the "X-Correlator" header in the request, + When the API Consumer includes the "x-correlator" header in the request, the API provider must include it in the response with the same value t hat was used in the request. Otherwise, it is optional to include the - "X-Correlator" header in the response with any valid value. + "x-correlator" header in the response with any valid value. Recommendation is to use UUID for values. required: false schema: @@ -410,8 +410,8 @@ components: 400BadRequest: description: Bad Request headers: - X-Correlator: - $ref: "#/components/headers/X-Correlator" + x-correlator: + $ref: "#/components/headers/x-correlator" content: application/json: schema: @@ -459,8 +459,8 @@ components: 401Unauthorized: description: Unauthorized headers: - X-Correlator: - $ref: "#/components/headers/X-Correlator" + x-correlator: + $ref: "#/components/headers/x-correlator" content: application/json: schema: @@ -478,8 +478,8 @@ components: 403Forbidden: description: Forbidden headers: - X-Correlator: - $ref: "#/components/headers/X-Correlator" + x-correlator: + $ref: "#/components/headers/x-correlator" content: application/json: schema: @@ -497,8 +497,8 @@ components: 404NotFound: description: Subscriber Not Found headers: - X-Correlator: - $ref: "#/components/headers/X-Correlator" + x-correlator: + $ref: "#/components/headers/x-correlator" content: application/json: schema: @@ -518,8 +518,8 @@ components: 405MethodNotAllowed: description: Method Not Allowed headers: - X-Correlator: - $ref: "#/components/headers/X-Correlator" + x-correlator: + $ref: "#/components/headers/x-correlator" content: application/json: schema: @@ -540,8 +540,8 @@ components: 406Unacceptable: description: Not Acceptable headers: - X-Correlator: - $ref: "#/components/headers/X-Correlator" + x-correlator: + $ref: "#/components/headers/x-correlator" content: application/json: schema: @@ -560,8 +560,8 @@ components: 429TooManyRequests: description: Too Many Requests headers: - X-Correlator: - $ref: "#/components/headers/X-Correlator" + x-correlator: + $ref: "#/components/headers/x-correlator" content: application/json: schema: @@ -582,8 +582,8 @@ components: 500InternalServerError: description: Internal Server Error headers: - X-Correlator: - $ref: "#/components/headers/X-Correlator" + x-correlator: + $ref: "#/components/headers/x-correlator" content: application/json: schema: @@ -598,8 +598,8 @@ components: 502BadGateway: description: Bad Gateway headers: - X-Correlator: - $ref: "#/components/headers/X-Correlator" + x-correlator: + $ref: "#/components/headers/x-correlator" content: application/json: schema: @@ -614,8 +614,8 @@ components: 503ServiceUnavailable: description: Service Unavailable headers: - X-Correlator: - $ref: "#/components/headers/X-Correlator" + x-correlator: + $ref: "#/components/headers/x-correlator" content: application/json: schema: @@ -630,8 +630,8 @@ components: 504GatewayTimeout: description: Gateway Time-Out headers: - X-Correlator: - $ref: "#/components/headers/X-Correlator" + x-correlator: + $ref: "#/components/headers/x-correlator" content: application/json: schema: From 28d0dc696d871041690a96a3acddf48d9c8bbb55 Mon Sep 17 00:00:00 2001 From: Kevsy Date: Fri, 7 Jun 2024 13:48:41 +0100 Subject: [PATCH 2/4] spectral fixes --- .../simple-edge-discovery.yaml | 20 +++++++++---------- 1 file changed, 10 insertions(+), 10 deletions(-) diff --git a/code/API_definitions/simple-edge-discovery.yaml b/code/API_definitions/simple-edge-discovery.yaml index 4f95432..122682a 100644 --- a/code/API_definitions/simple-edge-discovery.yaml +++ b/code/API_definitions/simple-edge-discovery.yaml @@ -79,7 +79,7 @@ info: Accept: application/json Phone-Number: +441234567890 ``` - + Example where API client is on a network-attached device: ``` @@ -87,7 +87,7 @@ info: Host: example.com Accept: application/json ``` - + # Responses ## Success @@ -95,7 +95,7 @@ info: A JSON object is returned containing an array with a single member object. This contains identifiers for the closest Edge Cloud Zone. The HTTP status code will be`200 OK`. An example response: - + ``` [ { @@ -207,7 +207,7 @@ paths: schema: type: string enum: - - closest + - closest - name: IPv4-Address in: header @@ -216,7 +216,7 @@ paths: example: "84.125.93.10" schema: $ref: "#/components/schemas/SingleIpv4Addr" - + - name: IPv6-Address in: header required: false @@ -234,7 +234,7 @@ paths: required: false schema: $ref: "#/components/schemas/NetworkAccessIdentifier" - + - name: Phone-Number in: header example: "+441234567890" @@ -245,7 +245,7 @@ paths: prefixed with '+'. schema: $ref: "#/components/schemas/PhoneNumber" - + - name: x-correlator in: header required: false @@ -306,7 +306,7 @@ components: description: OpenID Provider Configuration Information. type: openIdConnect openIdConnectUrl: .well-known/openid-configuration - + headers: x-correlator: description: | @@ -334,7 +334,7 @@ components: EdgeCloudZone: type: object - description: | + description: | An Edge Cloud Zone, uniquely identified by a combination of the value of the Edge Resource Name object and the value of the Provider object (the name of the cloud provider or operator hosting that @@ -381,7 +381,7 @@ components: This parameter appears when there is an error. A human readable explanation specific to this occurrence of the problem. - + PhoneNumber: description: A public identifier addressing a telephone subscription. In mobile networks it corresponds to the MSISDN (Mobile Station International Subscriber Directory Number). In order to be globally unique it has to be formatted in international format, according to E.164 standard, prefixed with '+'. type: string From 960751ddd5b55f004c67f792c9c64d5c7c44b3bc Mon Sep 17 00:00:00 2001 From: Kevsy Date: Fri, 7 Jun 2024 16:32:07 +0100 Subject: [PATCH 3/4] spectral fixes --- .../simple-edge-discovery.yaml | 48 +++++++++++-------- 1 file changed, 29 insertions(+), 19 deletions(-) diff --git a/code/API_definitions/simple-edge-discovery.yaml b/code/API_definitions/simple-edge-discovery.yaml index 122682a..70f5757 100644 --- a/code/API_definitions/simple-edge-discovery.yaml +++ b/code/API_definitions/simple-edge-discovery.yaml @@ -383,28 +383,38 @@ components: problem. PhoneNumber: - description: A public identifier addressing a telephone subscription. In mobile networks it corresponds to the MSISDN (Mobile Station International Subscriber Directory Number). In order to be globally unique it has to be formatted in international format, according to E.164 standard, prefixed with '+'. - type: string - pattern: '^\+[1-9][0-9]{4,14}$' - example: "+123456789" - + description: A public identifier addressing a telephone subscription. In + mobile networks it corresponds to the MSISDN (Mobile Station + International Subscriber Directory Number). In order to be globally + unique it has to be formatted in international format, according to + E.164 standard, prefixed with '+'. + type: string + pattern: '^\+[1-9][0-9]{4,14}$' + example: "+123456789" + NetworkAccessIdentifier: - description: A public identifier addressing a subscription in a mobile network. In 3GPP terminology, it corresponds to the GPSI formatted with the External Identifier ({Local Identifier}@{Domain Identifier}). Unlike the telephone number, the network access identifier is not subjected to portability ruling in force, and is individually managed by each operator. - type: string - example: "123456789@domain.com" - + description: A public identifier addressing a subscription in a mobile + network. In 3GPP terminology, it corresponds to the GPSI formatted with + the External Identifier ({Local Identifier}@{Domain Identifier}). + Unlike the telephone number, the network access identifier is not + subjected to portability ruling in force, and is individually managed + by each operator. + type: string + example: "123456789@domain.com" + SingleIpv4Addr: - description: A single IPv4 address with no subnet mask - type: string - format: ipv4 - example: "84.125.93.10" - + description: A single IPv4 address with no subnet mask + type: string + format: ipv4 + example: "84.125.93.10" + DeviceIpv6Address: - description: | - The device should be identified by the observed IPv6 address, or by any single IPv6 address from within the subnet allocated to the device (e.g. adding ::0 to the /64 prefix). - type: string - format: ipv6 - example: 2001:db8:85a3:8d3:1319:8a2e:370:7344 + description: The device should be identified by the observed IPv6 + address, or by any single IPv6 address from within the subnet allocated + to the device (e.g.adding ::0 to the /64 prefix). + type: string + format: ipv6 + example: "2001:db8:85a3:8d3:1319:8a2e:370:7344" responses: 400BadRequest: From 3672b221bd018e19381f1c40cd073661748f7b91 Mon Sep 17 00:00:00 2001 From: Kevsy Date: Mon, 10 Jun 2024 16:47:03 +0100 Subject: [PATCH 4/4] correct .spectral.yml file --- .spectral.yml | 4099 ++++--------------------------------------------- 1 file changed, 261 insertions(+), 3838 deletions(-) diff --git a/.spectral.yml b/.spectral.yml index 3f72c98..0042b3c 100644 --- a/.spectral.yml +++ b/.spectral.yml @@ -1,3838 +1,261 @@ - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - Commonalities/artifacts/linting_rules/.spectral.yml at main · camaraproject/Commonalities - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
- - - -
- Skip to content - - - - - - - - - - - - - - - - - - - - -
- - - - - - - - - - - - - - - - - -
- -
- - - - - - - - -
- - - - - - -
- - - - - - - - - - -
- - - - - - - - - - - - - - - - - -
- -
- - - - camaraproject  /   - Commonalities  /   - -
-
- - - -
- - -
-
- Clear Command Palette -
- - - - -
-
- Tip: - Type # to search pull requests -
-
- Type ? for help and tips -
-
- - -
-
- Tip: - Type # to search issues -
-
- Type ? for help and tips -
-
- - -
-
- Tip: - Type # to search discussions -
-
- Type ? for help and tips -
-
- - -
-
- Tip: - Type ! to search projects -
-
- Type ? for help and tips -
-
- - -
-
- Tip: - Type @ to search teams -
-
- Type ? for help and tips -
-
- - -
-
- Tip: - Type @ to search people and organizations -
-
- Type ? for help and tips -
-
- - -
-
- Tip: - Type > to activate command mode -
-
- Type ? for help and tips -
-
- - -
-
- Tip: - Go to your accessibility settings to change your keyboard shortcuts -
-
- Type ? for help and tips -
-
- - -
-
- Tip: - Type author:@me to search your content -
-
- Type ? for help and tips -
-
- - -
-
- Tip: - Type is:pr to filter to pull requests -
-
- Type ? for help and tips -
-
- - -
-
- Tip: - Type is:issue to filter to issues -
-
- Type ? for help and tips -
-
- - -
-
- Tip: - Type is:project to filter to projects -
-
- Type ? for help and tips -
-
- - -
-
- Tip: - Type is:open to filter to open content -
-
- Type ? for help and tips -
-
- - -
- -
-
- We’ve encountered an error and some results aren't available at this time. Type a new search or try again later. -
- - - No results matched your search - - - - - - - - - - - - - - - - Search for issues and pull requests - - # - - - - Search for issues, pull requests, discussions, and projects - - # - - - - Search for organizations, repositories, and users - - @ - - - - Search for projects - - ! - - - - Search for files - - / - - - - Activate command mode - - > - - - - Search your issues, pull requests, and discussions - - # author:@me - - - - Search your issues, pull requests, and discussions - - # author:@me - - - - Filter to pull requests - - # is:pr - - - - Filter to issues - - # is:issue - - - - Filter to discussions - - # is:discussion - - - - Filter to projects - - # is:project - - - - Filter to open issues, pull requests, and discussions - - # is:open - - - - - - - - - - - - - - - - - - -
- -
- - - - - - - - - - -
- - -
-
-
- - - - - - - - - - - - - - - - - - -
- Open in github.dev - Open in a new github.dev tab - Open in codespace - - - - - - - - - - - - - - - -

Latest commit

 

History

History
261 lines (242 loc) · 9.83 KB

.spectral.yml

File metadata and controls

261 lines (242 loc) · 9.83 KB
Raw
- - - - - -
- - - -
-
- -
- -
-

Footer

- - - - -
-
- - - - - © 2024 GitHub, Inc. - -
- - -
-
- - - - - - - - - - - - - - - - - - - - -
- -
-
- - - +# CAMARA Project - linting ruleset - documentation avaialable here: +# https://github.com/camaraproject/Commonalities/blob/main/documentation/Linting-rules.md +# Changelog: +# - 31.01.2024: Initial version +# - 19.03.2024: Corrected camara-http-methods rule + + +extends: "spectral:oas" +functions: + - camara-reserved-words + - camara-language-avoid-telco + - camara-security-no-secrets-in-path-or-query-parameters +functionsDir: "./lint_function" +rules: + # Built-in OpenAPI Specification ruleset. Each rule then can be enabled individually. + # The severity keyword is optional in rule definition and can be error, warn, info, hint, or off. The default value is warn. + contact-properties: false + duplicated-entry-in-enum: true + info-contact: true + info-description: true + info-license: true + license-url: true + no-$ref-siblings: error + no-eval-in-markdown: true + no-script-tags-in-markdown: true + openapi-tags: false + openapi-tags-alphabetical: false + openapi-tags-uniqueness: error + operation-description: true + operation-operationId: true + operation-operationId-unique: error + operation-operationId-valid-in-url: true + operation-parameters: true + operation-singular-tag: true + operation-success-response: true + operation-tags: true + operation-tag-defined: true + path-declarations-must-exist: true + path-keys-no-trailing-slash: true + path-not-include-query: true + path-params: error + tag-description: false + typed-enum: true + oas3-api-servers: true + oas3-examples-value-or-externalValue: true + oas3-operation-security-defined: false + oas3-parameter-description: false + oas3-schema: true + oas3-server-not-example.com: false + oas3-server-trailing-slash: true + oas3-unused-component: true + oas3-valid-media-example: true + oas3-valid-schema-example: true + # oas3-server-variables: true + + # Custom Rules Utilizing Spectral's Built-in Functions and JavaScript Implementations + + camara-language-avoid-telco: + message: "{{error}}" + severity: hint + description: | + This rule checks for telco-specific terminology in your API definitions and suggests more inclusive terms. + given: "$..*.*" + then: + function: camara-language-avoid-telco + recommended: false # Set to true/false to enable/disable this rule + + camara-oas-version: + message: "OpenAPI Version Error: The OpenAPI specification must adhere to version 3.0.3." + severity: error + description: | + This rule validates the OpenAPI version in your specification and requires compliance with version 3.0.3. + given: "$" + then: + field: openapi + function: pattern + functionOptions: + match: 3.0.3 + recommended: true # Set to true/false to enable/disable this rule + + camara-path-param-id: + message: "Path Parameter Naming Warning: Use 'resource_id' instead of just 'id' in path parameters." + severity: warn + description: | + This rule ensures consistent and descriptive naming for path parameters in your OpenAPI specification. + Please use 'resource_id' instead of just 'id' for your path parameters. + given: "$..parameters[?(@.in == 'path')]" + then: + field: name + function: pattern + functionOptions: + notMatch: \b(id|Id|ID|iD)\b + recommended: true # Set to true/false to enable/disable this rule + + camara-security-no-secrets-in-path-or-query-parameters: + message: "Sensitive data found in path: {{error}} Consider avoiding the use of Sesentive data " + severity: warn + description: | + This rule checks for sensitive data ('MSISDN' and 'IMSI') in API paths and suggests avoiding their use. + given: + - "$.paths" + then: + function: camara-security-no-secrets-in-path-or-query-parameters + recommended: true # Set to true/false to enable/disable this rule + + camara-http-methods: + description: "Ensure that all path URLs have valid HTTP methods (GET, PUT, POST, DELETE, PATCH, OPTIONS)." + message: "Invalid HTTP method for '{{path}}'. Must be one of get, put, post, delete, patch, options." + severity: error + given: $.paths[*][*]~ + then: + function: pattern + functionOptions: + match: "^(get|put|post|delete|patch|options|parameters)$" + recommended: true # Set to true/false to enable/disable this rule + + camara-get-no-request-body: + message: There must be no request body for Get and DELETE + severity: error + given: + - "$.paths.*.get" + - "$.paths.*.delete" + then: + field: requestBody + function: falsy + recommended: true # Set to true/false to enable/disable this rule + + camara-reserved-words: + message: "Reserved words found {{error}} Consider avoiding the use of reserved word " + severity: warn + description: | + This rule checks Reserved words must not be used in the following parts of an API specification [Paths, Request Body properties, Component, Operation Id, Security Schema] + given: + - "$.paths" # Paths + - "$..parameters[*]" # Path or Query Parameter Names: + - "$..components.schemas.*.properties.*" # Request and Response body parameter + - "$.paths.*." # Path and Operation Names: + - "$.components.securitySchemes" # Security Schemes: + - "$.components.*.*" # Component Names: + - "$.paths.*.*.operationId" # OperationIds: + then: + function: camara-reserved-words + recommended: true # Set to true/false to enable/disable this rule + + camara-routes-description: + message: "Functionality method description Warning: Each method should have description." + severity: warn + description: | + This rule checks if each operation (POST, GET, DELETE, PUT, PATCH, OPTIONS) in your API specification has a description. + Ensure that you have added a 'summary' field for each operation in your OpenAPI specification. + given: + - "$.paths.*.post" + - "$.paths.*.get" + - "$.paths.*.delete" + - "$.paths.*.put" + - "$.paths.*.patch" + - "$.paths.*.options" + then: + field: description + function: truthy + recommended: true # Set to true/false to enable/disable this rule + + camara-parameters-descriptions: + message: "Parameter description is missing or empty: {{error}}" + severity: warn + description: | + This Spectral rule ensures that each path parameter in the API specification has a descriptive and meaningful description. + given: + - "$.paths..parameters.*" + then: + field: description + function: truthy + recommended: true # Set to true/false to enable/disable this rule + + camara-response-descriptions: + message: "Parameter description is missing or empty: {{error}}" + severity: warn + description: | + This Spectral rule ensures that each responese object in the API specification has a descriptive and meaningful description. + given: + - "$.paths..responses.*" + then: + field: description + function: truthy + recommended: true # Set to true/false to enable/disable this rule + + camara-properties-descriptions: + message: "Property description is missing or empty: {{error}}" + severity: warn + description: | + This Spectral rule ensures that each propoerty within objects in the API specification has a descriptive and meaningful description. + given: + - "$.components.*.*" + - "$.components.*.*.properties.*" + then: + field: description + function: truthy + recommended: true # Set to true/false to enable/disable this rule + + camara-operation-summary: + message: "Operation Summary Warning: Each operation should include a short summary for better understanding." + severity: warn + description: | + This rule checks if each operation (POST, GET, DELETE, PUT, PATCH, OPTIONS) in your API specification has a meaningful summary. + Ensure that you have added a 'summary' field for each operation in your OpenAPI specification. + given: + - "$.paths.*.post" + - "$.paths.*.get" + - "$.paths.*.delete" + - "$.paths.*.put" + - "$.paths.*.patch" + - "$.paths.*.options" + then: + field: summary + function: truthy + recommended: true # Set to true/false to enable/disable this rule + + camara-discriminator-use: + description: | + Ensure that API definition YAML files with oneOf or anyOf sections include a discriminator object for serialization, deserialization, and validation. + severity: hint + given: "$..[?(@.oneOf || @.anyOf)]" + then: + field: discriminator + function: truthy + description: "Discriminator object is required when using oneOf or anyOf." + recommended: true # Set to true/false to enable/disable this rule + + camara-operationid-casing-convention: + message: Operation Id must be in Camel case "{{error}}" + severity: hint + description: | + This rule checks Operation ids should follow a specific case convention: camel case. + given: "$.paths.*.*.operationId" + then: + function: casing + functionOptions: + type: camel + recommended: true # Set to true/false to enable/disable this rule + + camara-schema-casing-convention: + description: This rule checks schema should follow a specific case convention pascal case. + message: "{{property}} should be pascal case (UppperCamelCase)" + severity: warn + given: $.components.schemas[*]~ + then: + function: casing + functionOptions: + type: pascal + recommended: true # Set to true/false to enable/disable this rule + + camara-parameter-casing-convention: + description: Paths should be kebab-case. + severity: error + message: "{{property}} is not kebab-case: {{error}}" + given: $.paths[*]~ + then: + function: pattern + functionOptions: + match: "^\/([a-z0-9]+(-[a-z0-9]+)*)?(\/[a-z0-9]+(-[a-z0-9]+)*|\/{.+})*$" # doesn't allow /asasd{asdas}sadas pattern or not closed braces + recommended: true # Set to true/false to enable/disable this rule