diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 082ddd6a..20c9319d 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -392,6 +392,8 @@ Resolves issue #123" - Each rule should have a corresponding documentation file in the relevant folder `/docs/spectral-rules/must/`, `/docs/spectral-rules/should/` or `/docs/spectral-rules/may/`. +- Every rule definition **MUST** set `documentationUrl` so Spectral CLI can surface a deep link to the matching documentation page (for example `https://ukhsa-collaboration.github.io/standards-org/api-design-guidelines/spectral-rules/must//`). + - Include references to the relevant sections of the API guidelines. - [Test the rules][25] that you have created or modified. @@ -403,7 +405,7 @@ Resolves issue #123" - Test new rules against the example specifications in the `/example/` directory (you may need to modify the example definition to test your rules). ```bash - spectral lint example/example.1.0.0.oas.yml + spectral lint example/example.1.0.0.oas.yml --show-documentation-url ``` - Verify that rules produce the expected results for both valid and invalid API definitions. diff --git a/docs/spectral-rules/index.md b/docs/spectral-rules/index.md index 954c8264..4a73a3ed 100644 --- a/docs/spectral-rules/index.md +++ b/docs/spectral-rules/index.md @@ -57,9 +57,12 @@ echo "extends: ['@ukhsa-collaboration/spectral-rules']" > .spectral.yml then you can just run the following. ```sh -npx spectral lint openapi-definition.yml +npx spectral lint openapi-definition.yml --show-documentation-url ``` +> [!TIP] Show documentation links +> Spectral CLI v6.15.0 and newer support `--show-documentation-url`, which prints the `documentationUrl` value for every rule violation. Always include this flag so developers can jump straight to the detailed guidance that explains how to fix an issue. + ### Review and fix any reported issues Once the linter has highlighted any issues or errors, review and fix to ensure your OpenAPI definition remains compliant with the UKHSA guidelines. @@ -115,10 +118,10 @@ jobs: - name: Lint OpenAPI specifications run: | npx spectral --version - npx spectral lint "*.{json,yml,yaml}" -r ${{ GITHUB.WORKSPACE }}/node_modules/@ukhsa-collaboration/spectral-rules/.spectral.yaml -f github-actions + npx spectral lint "*.{json,yml,yaml}" -r ${{ GITHUB.WORKSPACE }}/node_modules/@ukhsa-collaboration/spectral-rules/.spectral.yaml -f github-actions --show-documentation-url # Example: Only lint OpenAPI files - # npx spectral lint "@(openapi|swagger|*api)*.{json,yml,yaml}" -r ${{ GITHUB.WORKSPACE }}/node_modules/@ukhsa-collaboration/spectral-rules/.spectral.yaml -f github-actions + # npx spectral lint "@(openapi|swagger|*api)*.{json,yml,yaml}" -r ${{ GITHUB.WORKSPACE }}/node_modules/@ukhsa-collaboration/spectral-rules/.spectral.yaml -f github-actions --show-documentation-url ``` diff --git a/docs/spectral-rules/should/should-always-return-json-objects-as-top-level-data-structures.md b/docs/spectral-rules/should/should-always-return-json-objects-as-top-level-data-structures.md index e880638f..d74beeab 100644 --- a/docs/spectral-rules/should/should-always-return-json-objects-as-top-level-data-structures.md +++ b/docs/spectral-rules/should/should-always-return-json-objects-as-top-level-data-structures.md @@ -31,7 +31,7 @@ requestBody: [UKHSA Guidelines API Design][1] -[Zalando Guideline 210][2] +[Zalando Guideline 110][2] [1]: ../../api-guidelines/api-design.md#response-format -[2]: https://opensource.zalando.com/restful-api-guidelines/#210 +[2]: https://opensource.zalando.com/restful-api-guidelines/#110 diff --git a/ukhsa.oas.rules.yml b/ukhsa.oas.rules.yml index b8257ecd..dfd60fd1 100644 --- a/ukhsa.oas.rules.yml +++ b/ukhsa.oas.rules.yml @@ -17,6 +17,7 @@ rules: # Conditional overrides based on API type override-severity-pygeoapi: message: "Adjusting severity for pygeoapi definitions" + documentationUrl: https://ukhsa-collaboration.github.io/standards-org/api-design-guidelines/spectral-rules/severity-overrides/ given: "$" then: function: overrideSeverity @@ -58,6 +59,7 @@ rules: recommended: true description: Properties must use lower camel case. message: Properties must use lower camel case. + documentationUrl: https://ukhsa-collaboration.github.io/standards-org/api-design-guidelines/spectral-rules/must/must-use-camel-case-for-property-names/ # MUST Query parameters must use lower camel case. # => /docs/spectral-rules/must/must-use-camel-case-for-query-parameters.md @@ -73,6 +75,7 @@ rules: recommended: true description: Query parameters must use lower camel case. message: Query parameters must use lower camel case. + documentationUrl: https://ukhsa-collaboration.github.io/standards-org/api-design-guidelines/spectral-rules/must/must-use-camel-case-for-query-parameters/ # MUST The `info` object must have an `x-audience` that matches at least one of these values: company-internal, partner-external, premium-external or public-external. # => /docs/spectral-rules/must/must-have-info-api-audience.md @@ -95,6 +98,7 @@ rules: recommended: true description: 'The `info` object must have an `x-audience` that matches at least one of these values: company-internal, partner-external, premium-external or public-external.' message: Missing or wrong `info.x-audience`, {{error}}. + documentationUrl: https://ukhsa-collaboration.github.io/standards-org/api-design-guidelines/spectral-rules/must/must-have-info-api-audience/ # MUST Path must start with a slash and must not end with a slash. # => /docs/spectral-rules/must/must-use-normalized-paths.md @@ -109,6 +113,7 @@ rules: match: ^\/($|[^\/].*[^\/]$) description: "Path must start with a slash and must not end with a slash (except root path '/')" message: "Path must start with a slash and must not end with a slash (except root path '/')" + documentationUrl: https://ukhsa-collaboration.github.io/standards-org/api-design-guidelines/spectral-rules/must/must-use-normalized-paths/ # SHOULD APIs SHOULD have a root path (`/`) defined. # => /docs/spectral-rules/must/should-define-api-root.md @@ -122,6 +127,7 @@ rules: recommended: true description: Good documentation is always welcome, but API consumers should be able to get a pretty long way through interaction with the API alone. They should at least know they're looking at the right place instead of getting a 404 or random 500 error as is common in some APIs. message: APIs SHOULD have a root path (`/`) defined. + documentationUrl: https://ukhsa-collaboration.github.io/standards-org/api-design-guidelines/spectral-rules/should/should-define-api-root/ # MUST Root path must define a 200 response.. # => /docs/spectral-rules/must/must-return-200-for-api-root.md @@ -135,6 +141,7 @@ rules: recommended: true description: 'Root path must define a 200 response.' message: 'Root path must define a 200 response.' + documentationUrl: https://ukhsa-collaboration.github.io/standards-org/api-design-guidelines/spectral-rules/must/must-return-200-for-api-root/ # MUST `ApiInfo` schema must include this set of minimal required properties and validations. # => /docs/spectral-rules/must/must-use-valid-version-info-schema.md @@ -148,6 +155,7 @@ rules: recommended: true description: '`ApiInfo` schema must include this set of minimal required properties and validations.' message: '{{error}}' + documentationUrl: https://ukhsa-collaboration.github.io/standards-org/api-design-guidelines/spectral-rules/must/must-use-valid-version-info-schema/ # MUST The `info` object must have an `x-value-chain` that matches at least one of these values: prevent, detect, analyse, respond, cross-cutting or enabling. # => /docs/spectral-rules/must/must-have-info-value-chain.md @@ -171,6 +179,7 @@ rules: recommended: true description: 'The `info` object must have an `x-value-chain` that matches at least one of these values: prevent, detect, analyse, respond, cross-cutting or enabling.' message: "Missing or wrong `info.x-value-chain`, {{error}}." + documentationUrl: https://ukhsa-collaboration.github.io/standards-org/api-design-guidelines/spectral-rules/must/must-have-info-value-chain/ # MUST ALL requests MUST go through `https` protocol only # => /docs/spectral-rules/must/must-use-https-protocol-only.md @@ -185,6 +194,7 @@ rules: recommended: true description: ALL requests MUST go through `https` protocol only message: Servers MUST be `https` and no other protocol is allowed. + documentationUrl: https://ukhsa-collaboration.github.io/standards-org/api-design-guidelines/spectral-rules/must/must-use-https-protocol-only/ # MUST APIs MUST NOT use `HTTP` Basic Authentication. # => /docs/spectral-rules/must/must-not-use-http-basic-authentication.md @@ -199,6 +209,7 @@ rules: notMatch: basic recommended: true message: APIs MUST NOT use `HTTP` Basic Authentication. + documentationUrl: https://ukhsa-collaboration.github.io/standards-org/api-design-guidelines/spectral-rules/must/must-not-use-http-basic-authentication/ description: >- HTTP Basic is an inherently insecure way to pass credentials to the API. They're placed in the URL in base64 which can be decrypted easily. Even if you're using a token, there are far better ways to handle passing tokens to an API which are less likely to leak. @@ -223,6 +234,7 @@ rules: recommended: true description: Every request SHOULD support at least one `application/json` content type message: Every request SHOULD support at least one `application/json` content type. + documentationUrl: https://ukhsa-collaboration.github.io/standards-org/api-design-guidelines/spectral-rules/should/should-support-application-json-content-request-body/ # MUST A GET request MUST NOT accept a request body. # => /docs/spectral-rules/must/must-not-define-request-body-for-get-requests.md @@ -235,6 +247,7 @@ rules: recommended: true description: Defining a request body on a HTTP GET is in some implementations, but is increasingly frowned upon due to the confusion that comes from unspecified behavior in the HTTP specification. message: A GET request MUST NOT accept a request body. + documentationUrl: https://ukhsa-collaboration.github.io/standards-org/api-design-guidelines/spectral-rules/must/must-not-define-request-body-for-get-requests/ # MUST All APIs MUST have a security scheme defined. # => /docs/spectral-rules/must/must-define-security-schemes.md @@ -248,6 +261,7 @@ rules: recommended: true description: This API definition does not have any security scheme defined, which means the entire API is open to the public. That's probably not what you want, even if all the data is read-only. Setting lower rate limits for the public and letting known consumers use more resources is a handy path to monetization, and helps know who your power users are when changes need feedback or migration, even if not just good practice. message: All APIs MUST have a security scheme defined. + documentationUrl: https://ukhsa-collaboration.github.io/standards-org/api-design-guidelines/spectral-rules/must/must-define-security-schemes/ # SHOULD `201 Created` responses to `POST` methods SHOULD have a `Location` header identifying the location of the newly created resource. # => /docs/spectral-rules/should/should-have-location-header-in-201-response.md @@ -292,6 +306,7 @@ rules: recommended: true description: '`201 Created` responses to `POST` methods SHOULD have a `Location` header identifying the location of the newly created resource.' message: '{{error}}' + documentationUrl: https://ukhsa-collaboration.github.io/standards-org/api-design-guidelines/spectral-rules/should/should-have-location-header-in-201-response/ # MUST Each operation MUST define 400, 404, and 500 responses using `application/problem+json` with examples. # => /docs/spectral-rules/must/must-define-critical-problem-responses.md @@ -299,6 +314,7 @@ rules: must-define-critical-problem-responses: description: "Operations must define 400, 404, 500 with examples and application/problem+json" message: "{{error}}" + documentationUrl: https://ukhsa-collaboration.github.io/standards-org/api-design-guidelines/spectral-rules/must/must-define-critical-problem-responses/ severity: warn given: $.paths[*][*] then: @@ -312,6 +328,7 @@ rules: must-define-security-problem-responses: description: "Operations with their own non-empty 'security' MUST define 401 and 403" message: "{{error}}" + documentationUrl: https://ukhsa-collaboration.github.io/standards-org/api-design-guidelines/spectral-rules/must/must-define-security-problem-responses/ severity: warn given: $.paths[*][*] then: @@ -336,6 +353,7 @@ rules: recommended: true description: 'The `info` object SHOULD contain `x-contains-sensitive-data` to indicate presence of sensitive data such as PII or PHI.' message: "Missing or wrong 'info.x-contains-sensitive-data', should be 'boolean'." + documentationUrl: https://ukhsa-collaboration.github.io/standards-org/api-design-guidelines/spectral-rules/should/should-have-info-x-contains-sensitive-data/ # MAY include `info.x-api-type` to indicate API category; enforce enum values when present. # => /docs/spectral-rules/may/may-have-info-x-api-type.md @@ -357,3 +375,4 @@ rules: recommended: true description: 'APIs MAY include info.x-api-type to indicate API category. When present, it MUST be one of: standard, pygeoapi. When omitted, standard is assumed.' message: "Missing or wrong 'info.x-api-type'. Assuming 'standard'. Valid values: standard, pygeoapi." + documentationUrl: https://ukhsa-collaboration.github.io/standards-org/api-design-guidelines/spectral-rules/may/may-have-info-x-api-type/ diff --git a/zalando.oas.rules.yml b/zalando.oas.rules.yml index 2aef0600..5a811d00 100644 --- a/zalando.oas.rules.yml +++ b/zalando.oas.rules.yml @@ -28,6 +28,7 @@ rules: function: isObjectSchema description: 'The top-level data structure for a `request body` or `response body` must be an object.' message: Top-level data structure must be an object + documentationUrl: https://ukhsa-collaboration.github.io/standards-org/api-design-guidelines/spectral-rules/should/should-always-return-json-objects-as-top-level-data-structures/ # SHOULD '`enum` values should use the marker `x-extensible-enum` rather than `enum`.' # => /docs/spectral-rules/should/should-use-x-extensible-enum.md @@ -39,6 +40,7 @@ rules: function: undefined description: '`enum` values should use the marker `x-extensible-enum` rather than `enum`.' message: Should use `x-extensible-enum` instead of `enum` + documentationUrl: https://ukhsa-collaboration.github.io/standards-org/api-design-guidelines/spectral-rules/should/should-use-x-extensible-enum/ # MUST Path must not contain versions. # => /docs/spectral-rules/must/must-not-use-uri-versioning.md @@ -52,20 +54,21 @@ rules: notMatch: /v[0-9]+/ description: Path must not contain versions. message: Path must not contain versioning + documentationUrl: https://ukhsa-collaboration.github.io/standards-org/api-design-guidelines/spectral-rules/must/must-not-use-uri-versioning/ # MUST 'Property names must use snake-case strings that match this pattern: `^[a-z_][a-z_0-9]*$`.' - # => /docs/spectral-rules/must/must-use-snake-case-for-property-names.md + # => turned off must-use-snake-case-for-property-names: given: $.paths.*.*[responses,requestBody]..content..schema..properties.*~ severity: error - then: then: function: casing functionOptions: type: snake description: 'Property names must use snake-case strings that match this pattern: `^[a-z_][a-z_0-9]*$`.' message: Property name has to be ASCII snake_case + documentationUrl: https://opensource.zalando.com/restful-api-guidelines/#118 # MUST Path segments must use lowercase letters and hyphens to separate words. # => /docs/spectral-rules/must/must-use-lowercase-with-hyphens-for-path-segments.md @@ -79,9 +82,10 @@ rules: match: ^(([\/a-z][a-z0-9\-\/]*)?({[^}]*})?)+$ description: Path segments must use lowercase letters and hyphens to separate words. message: Path segments have to be lowercase separate words with hyphens. + documentationUrl: https://ukhsa-collaboration.github.io/standards-org/api-design-guidelines/spectral-rules/must/must-use-lowercase-with-hyphens-for-path-segments/ # MUST Query parameter must use snake-case and match this pattern: `^[a-z][_a-z0-9]*$`. - # => + # => turned off must-use-snake-case-for-query-parameters: given: $.paths.*.*.parameters[?(@ && @.in=='query')].name @@ -120,8 +124,8 @@ rules: ``` - [Zalando Guideline 130](https://opensource.zalando.com/restful-api-guidelines/#130) message: Query parameters must be snake_case + documentationUrl: https://opensource.zalando.com/restful-api-guidelines/#130 # SHOULD Header parameters should use hyphenated Pascal case. # => /docs/spectral-rules/should/should-use-hyphenated-pascal-case-for-header-parameters.md @@ -135,8 +139,12 @@ rules: type: pascal separator: char: '-' - description: Header parameters should use hyphenated Pascal case. + description: Header parameters should use hyphenated Pascal case. message: Header parameters should be Hyphenated-Pascal-Case + documentationUrl: https://ukhsa-collaboration.github.io/standards-org/api-design-guidelines/spectral-rules/should/should-use-hyphenated-pascal-case-for-header-parameters/ + + # SHOULD Base path should not include `api`. + # => turned off should-not-use-api-as-base-path: given: $.paths.*~ @@ -168,8 +176,8 @@ rules: ``` - [Zalando Guideline 135](https://opensource.zalando.com/restful-api-guidelines/#135) message: Path should not start with /api + documentationUrl: https://opensource.zalando.com/restful-api-guidelines/#135 # MUST Path segments must not contain duplicate slashes. # => /docs/spectral-rules/must/must-use-normalized-paths-without-empty-path-segments.md @@ -183,9 +191,10 @@ rules: notMatch: // description: Path segments must not contain duplicate slashes. message: Empty path segments are not allowed + documentationUrl: https://ukhsa-collaboration.github.io/standards-org/api-design-guidelines/spectral-rules/must/must-use-normalized-paths-without-empty-path-segments/ # MUST Path with trailing slash is not allowed. - # => /docs/spectral-rules/must/must-use-normalized-paths-without-trailing-slash.md + # => turned off must-use-normalized-paths-without-trailing-slash: given: $.paths.*~ @@ -196,6 +205,7 @@ rules: notMatch: /$ description: Path with trailing slash is not allowed. message: Path with trailing slash is not allowed + documentationUrl: https://opensource.zalando.com/restful-api-guidelines/#136 # SHOULD Resource types (root URL paths) should be limited to no more than eight. # => /docs/spectral-rules/should/should-limit-number-of-resource-types.md @@ -209,6 +219,7 @@ rules: max: 8 description: Resource types (root URL paths) should be limited to no more than eight. message: '{{error}}' + documentationUrl: https://ukhsa-collaboration.github.io/standards-org/api-design-guidelines/spectral-rules/should/should-limit-number-of-resource-types/ # SHOULD Path should contain no more than 3 sub-resources (nested resources with non-root URL paths). # => /docs/spectral-rules/should/should-limit-number-of-sub-resource-levels.md @@ -222,6 +233,7 @@ rules: match: ^\/[^\/]*((\/{[^}]*})*\/[^\/]*(\/{[^}]*})*){0,3}\/?$ description: Path should contain no more than 3 sub-resources (nested resources with non-root URL paths). message: Sub-resource levels should by <= 3 + documentationUrl: https://ukhsa-collaboration.github.io/standards-org/api-design-guidelines/spectral-rules/should/should-limit-number-of-sub-resource-levels/ # SHOULD Path should contain no more than 3 sub-resources (nested resources with non-root URL paths). # => /docs/spectral-rules/should/should-use-standard-http-status-codes.md @@ -283,6 +295,7 @@ rules: - default description: '`response` should use standard HTTP status codes.' message: '{{property}} is not a standardized response code' + documentationUrl: https://ukhsa-collaboration.github.io/standards-org/api-design-guidelines/spectral-rules/should/should-use-standard-http-status-codes/ # MUST Each `operation` must include a default error response that combines multiple errors. # => /docs/spectral-rules/must/must-specify-default-response.md @@ -295,6 +308,7 @@ rules: field: default description: Each `operation` must include a default error response that combines multiple errors. message: Operation does not contain a default response + documentationUrl: https://ukhsa-collaboration.github.io/standards-org/api-design-guidelines/spectral-rules/must/must-specify-default-response/ # MUST The content type for the default response must be `application/problem+json`. # => /docs/spectral-rules/must/must-use-problem-json-as-default-response.md @@ -307,6 +321,7 @@ rules: field: content.application/problem+json description: The content type for the default response must be `application/problem+json`. message: Operation must use problem json as default response + documentationUrl: https://ukhsa-collaboration.github.io/standards-org/api-design-guidelines/spectral-rules/must/must-use-problem-json-as-default-response/ # MUST `number` properties must have a format defined (`float`, `double`, or `decimal`). # => /docs/spectral-rules/must/must-define-a-format-for-number-types.md @@ -323,6 +338,7 @@ rules: field: format description: '`number` properties must have a format defined (`float`, `double`, or `decimal`).' message: Numeric properties must have valid format specified + documentationUrl: https://ukhsa-collaboration.github.io/standards-org/api-design-guidelines/spectral-rules/must/must-define-a-format-for-number-types/ # MUST `integer` properties must have a format defined (`int32`, `int64`, or `bigint`). # => /docs/spectral-rules/must/must-define-a-format-for-integer-types.md @@ -339,6 +355,7 @@ rules: field: format description: '`integer` properties must have a format defined (`int32`, `int64`, or `bigint`).' message: Numeric properties must have valid format specified + documentationUrl: https://ukhsa-collaboration.github.io/standards-org/api-design-guidelines/spectral-rules/must/must-define-a-format-for-integer-types/ # SHOULD Response content should use a standard media type `application/json` or `application/problem+json` (required for problem schemas). # => /docs/spectral-rules/should/should-prefer-standard-media-type-names.md @@ -352,6 +369,7 @@ rules: match: ^application\/(problem\+)?json$|^[a-zA-Z0-9_]+\/[-+.a-zA-Z0-9_]+;(v|version)=[0-9]+$ description: Response content should use a standard media type `application/json` or `application/problem+json` (required for problem schemas). message: Response content should use a standard media type `application/json` or `application/problem+json` (required for problem schemas). + documentationUrl: https://ukhsa-collaboration.github.io/standards-org/api-design-guidelines/spectral-rules/should/should-prefer-standard-media-type-names/ # MUST Response content should use a standard media type `application/json` or `application/problem+json` (required for problem schemas). # => /docs/spectral-rules/must/must-use-problem-json-for-errors.md @@ -366,6 +384,7 @@ rules: - application/problem+json description: The content type for 4xx and 5xx status codes must be `application/problem+json`. message: Error response must be application/problem+json + documentationUrl: https://ukhsa-collaboration.github.io/standards-org/api-design-guidelines/spectral-rules/must/must-use-problem-json-for-errors/ # MUST `Problem` schema must include this set of minimal required properties and validations # => /docs/spectral-rules/must/must-use-valid-problem-json-schema.md @@ -378,6 +397,7 @@ rules: field: schema description: '`Problem` schema must include this set of minimal required properties and validations.' message: '{{error}}' + documentationUrl: https://ukhsa-collaboration.github.io/standards-org/api-design-guidelines/spectral-rules/must/must-use-valid-problem-json-schema/ # MUST The `info` object must have a `description` property defined. # => /docs/spectral-rules/must/must-have-info-description.md @@ -390,6 +410,7 @@ rules: field: description description: The `info` object must have a `description` property defined. message: Must have API description defined in `info.description` + documentationUrl: https://ukhsa-collaboration.github.io/standards-org/api-design-guidelines/spectral-rules/must/must-have-info-description/ # MUST The `info` object must have a `contact:name` property that contains a valid name for the team or person responsible for the API. # => /docs/spectral-rules/must/must-have-info-contact-name.md @@ -402,6 +423,7 @@ rules: field: contact.name description: The `info` object must have a `contact:name` property that contains a valid name for the team or person responsible for the API. message: Must have name defined in `info.contact.name` + documentationUrl: https://ukhsa-collaboration.github.io/standards-org/api-design-guidelines/spectral-rules/must/must-have-info-contact-name/ # MUST The `info` object must have a `contact:url` property that contains a valid URL to contact the team or person responsible for the API. # => /docs/spectral-rules/must/must-have-info-contact-url.md @@ -414,6 +436,7 @@ rules: field: contact.url description: The `info` object must have a `contact:url` property that contains a valid URL to contact the team or person responsible for the API. message: Must have email defined in `info.contact.url` + documentationUrl: https://ukhsa-collaboration.github.io/standards-org/api-design-guidelines/spectral-rules/must/must-have-info-contact-url/ # MUST The `info` object must have a `contact email` property that contains a valid email address for the responsible team. # => /docs/spectral-rules/must/must-have-info-contact-email.md @@ -426,6 +449,7 @@ rules: field: contact.email description: The `info` object must have a `contact email` property that contains a valid email address for the responsible team. message: Must have email defined in `info.contact.email` + documentationUrl: https://ukhsa-collaboration.github.io/standards-org/api-design-guidelines/spectral-rules/must/must-have-info-contact-email/ # MUST The `info` object must have an `x-api-id` property that conforms to this pattern: `^[a-z0-9][a-z0-9-:.]{6,62}[a-z0-9]$` # => turned off @@ -454,7 +478,7 @@ rules: info: api-id: title: Payments API - ``` + ``` **Valid Example** @@ -464,11 +488,11 @@ rules: info: x-api-id: d0184f38-b98d-11e7-9c56-68f728c1ba70 - title: Payments API - ``` + title: Payments API + ``` - [Zalando Guideline 218](https://opensource.zalando.com/restful-api-guidelines/#218) and [Zalando Guideline 215](https://opensource.zalando.com/restful-api-guidelines/#215) message: Missing `info.x-api-id`. + documentationUrl: https://opensource.zalando.com/restful-api-guidelines/#215 # MUST The `info` object must have an `x-audience` that matches at least one of these values: # => turned off @@ -485,6 +509,7 @@ rules: field: x-audience description: Missing or wrong `info.x-audience`. message: Missing or wrong `info.x-audience`. + documentationUrl: https://opensource.zalando.com/restful-api-guidelines/#219 # SHOULD `enum` and `x-extensible-enum` values should be in UPPER_SNAKE_CASE format. # => /docs/spectral-rules/should/should-declare-enum-values-using-upper-snake-case-format.md @@ -498,6 +523,7 @@ rules: match: ^[A-Z][A-Z_0-9]*$ description: '`enum` and `x-extensible-enum` values should be in UPPER_SNAKE_CASE format.' message: Enum values should be in UPPER_SNAKE_CASE format + documentationUrl: https://ukhsa-collaboration.github.io/standards-org/api-design-guidelines/spectral-rules/should/should-declare-enum-values-using-upper-snake-case-format/ # MUST The `info` object must have a `title` property defined. # => /docs/spectral-rules/must/must-have-info-title.md @@ -510,6 +536,7 @@ rules: field: title description: The `info` object must have a `title` property defined. message: Must have API title defined in `info.title` + documentationUrl: https://ukhsa-collaboration.github.io/standards-org/api-design-guidelines/spectral-rules/must/must-have-info-title/ # MUST The `info` object must have a `version` property that follows [semantic rules](http://semver.org/spec/v2.0.0.html) to distinguish API versions. # => /docs/spectral-rules/must/must-have-info-version.md @@ -528,3 +555,4 @@ rules: field: version description: The `info` object must have a `version` property that follows [semantic rules](http://semver.org/spec/v2.0.0.html) to distinguish API versions. message: Must have API version defined in `info.version` + documentationUrl: https://ukhsa-collaboration.github.io/standards-org/api-design-guidelines/spectral-rules/must/must-have-info-version/