ThatGuyJack/nginx-proxy-manager
1
0
Fork 0
mirror of https://github.com/NginxProxyManager/nginx-proxy-manager.git synced 2025-10-31 07:43:33 +00:00
Code Issues Actions Packages Projects Releases Wiki Activity

Swagger/openapi schema mega fixes and Cypress validation/enforcement

Browse Source
This commit is contained in:
Jamie Curnow
2025-10-29 20:15:00 +10:00
parent 89abb9d559
commit 906ce8ced2
80 changed files with 2007 additions and 543 deletions
Download Patch File Download Diff File Expand all files Collapse all files

21
test/cypress/e2e/api/SwaggerSchema.cy.js Normal file
View File

@@ -0,0 +1,21 @@
/// <reference types="cypress" />
const SWAGGER_SCHEMA_FILENAME = 'results/swagger-schema.json';
describe('Swagger Schema Linting', () => {
it('Should be a completely valid schema', () => {
// Save the schema to a file and lint it
cy.request('/api/schema')
.then((response) => {
const fileContent = response.body;
cy.writeFile(SWAGGER_SCHEMA_FILENAME, fileContent);
})
.then(() => {
cy.exec(`yarn swagger-lint '${SWAGGER_SCHEMA_FILENAME}'`)
.then((result) => {
cy.log("Swagger Vacuum Results:\n", result.stdout);
expect(result.code).to.eq(0);
});
});
});
});

4
test/package.json
View File

@@ -5,6 +5,7 @@
"main": "index.js",
"dependencies": {
"@jc21/cypress-swagger-validation": "^0.3.2",
"@quobix/vacuum": "^0.19.4",
"axios": "^1.7.9",
"cypress": "^14.0.1",
"cypress-multi-reporters": "^2.0.5",
@@ -20,7 +21,8 @@
},
"scripts": {
"cypress": "HTTP_PROXY=127.0.0.1:8128 HTTPS_PROXY=127.0.0.1:8128 cypress open --config-file=cypress/config/ci.js",
"cypress:headless": "HTTP_PROXY=127.0.0.1:8128 HTTPS_PROXY=127.0.0.1:8128 cypress run --config-file=cypress/config/ci.js"
"cypress:headless": "HTTP_PROXY=127.0.0.1:8128 HTTPS_PROXY=127.0.0.1:8128 cypress run --config-file=cypress/config/ci.js",
"swagger-lint": "vacuum lint -b -q -d -a -n=warn"
},
"author": "",
"license": "ISC"

971
test/vacuum-rules.yaml Normal file
View File

@@ -0,0 +1,971 @@
description: Recommended rules for a high quality specification.
documentationUrl: https://quobix.com/vacuum/rulesets/recommended
rules:
component-description:
category:
description: Documentation is really important, in OpenAPI, just about everything can and should have a description. This set of rules checks for absent descriptions, poor quality descriptions (copy/paste), or short descriptions.
id: descriptions
name: Descriptions
description: Component description check
formats:
- oas3
- oas3_1
- oas3_2
given: $
howToFix: Components are the inputs and outputs of a specification. A user needs to be able to understand each component and what id does. Descriptions are critical to understanding components. Add a description!
id: component-description
recommended: true
resolved: true
severity: warn
then:
function: oasComponentDescriptions
type: validation
duplicate-paths:
category:
description: Operations are the core of the contract, they define paths and HTTP methods. These rules check operations have been well constructed, looks for operationId, parameter, schema and return types in depth.
id: operations
name: Operations
description: Paths cannot be duplicated; only the last definition will be kept.
formats:
- oas3
- oas3_1
- oas3_2
given: $
howToFix: Duplicate path definitions found in your OpenAPI specification. In YAML, duplicate keys are allowed, but only the last occurrence is used. This means earlier path definitions are silently ignored, which can lead to missing API endpoints in your specification.
id: duplicate-paths
recommended: true
severity: error
then:
function: duplicatePaths
type: validation
duplicated-entry-in-enum:
category:
description: Schemas are how request bodies and response payloads are defined. They define the data going in and the data flowing out of an operation. These rules check for structural validity, checking types, checking required fields and validating correct use of structures.
id: schemas
name: Schemas
description: Enum values must not have duplicate entry
formats:
- oas3
- oas3_1
- oas3_2
- oas2
given: $
howToFix: Enums need to be unique, you can't duplicate them in the same definition. Please remove the duplicate value.
id: duplicated-entry-in-enum
recommended: true
severity: error
then:
function: duplicatedEnum
type: validation
info-description:
category:
description: The info object contains licencing, contact, authorship details and more. Checks to confirm required details have been completed.
id: information
name: Contract Information
description: Info section is missing a description
formats:
- oas3
- oas3_1
- oas3_2
- oas2
given: $
howToFix: The 'info' section is missing a description, surely you want people to know what this spec is all about, right?
id: info-description
recommended: true
resolved: true
severity: error
then:
function: infoDescription
type: validation
info-license-spdx:
category:
description: The info object contains licencing, contact, authorship details and more. Checks to confirm required details have been completed.
id: information
name: Contract Information
description: License section cannot contain both an identifier and a URL, they are mutually exclusive.
formats:
- oas3
- oas3_1
- oas3_2
- oas2
given: $
howToFix: A license can contain either a URL or an SPDX identifier, but not both, They are mutually exclusive and cannot both be present. Choose one or the other
id: info-license-spdx
recommended: true
resolved: true
severity: error
then:
function: infoLicenseURLSPDX
type: validation
migrate-zally-ignore:
category:
description: Validation rules make sure that certain characters or patterns have not been used that may cause issues when rendering in different types of applications.
id: validation
name: Validation
description: x-zally-ignore keys should be migrated to x-lint-ignore for compatibility with vacuum
formats:
- oas3
- oas3_1
- oas3_2
- oas2
given: $
howToFix: Migrate x-zally-ignore directives to vacuum's x-lint-ignore. Rename the key to x-lint-ignore and update the ignored rule id to the vacuum equivalent rule.
id: migrate-zally-ignore
recommended: true
resolved: true
severity: warn
then:
function: migrateZallyIgnore
type: validation
no-$ref-siblings:
category:
description: Schemas are how request bodies and response payloads are defined. They define the data going in and the data flowing out of an operation. These rules check for structural validity, checking types, checking required fields and validating correct use of structures.
id: schemas
name: Schemas
description: $ref values cannot be placed next to other properties (like a description)
formats:
- oas2
- oas3
given: $
howToFix: $ref values must not be placed next to sibling nodes, There should only be a single node when using $ref. A common mistake is adding 'description' next to a $ref. This is wrong. remove all siblings!
id: no-$ref-siblings
recommended: true
severity: error
then:
function: refSiblings
type: validation
no-ambiguous-paths:
category:
description: Operations are the core of the contract, they define paths and HTTP methods. These rules check operations have been well constructed, looks for operationId, parameter, schema and return types in depth.
id: operations
name: Operations
description: Paths need to resolve unambiguously from one another
formats:
- oas3
- oas3_1
- oas3_2
- oas2
given: $
howToFix: Paths must all resolve unambiguously, they can't be confused with one another (/{id}/ambiguous and /ambiguous/{id} are the same thing. Make sure every path and the variables used are unique and do conflict with one another. Check the ordering of variables and the naming of path segments.
id: no-ambiguous-paths
recommended: true
resolved: true
severity: error
then:
function: noAmbiguousPaths
type: validation
no-eval-in-markdown:
category:
description: Validation rules make sure that certain characters or patterns have not been used that may cause issues when rendering in different types of applications.
id: validation
name: Validation
description: Markdown descriptions must not have `eval()` statements'
formats:
- oas3
- oas3_1
- oas3_2
- oas2
given: $
howToFix: Remove all references to 'eval()' in the description. These can be used by malicious actors to embed code in contracts that is then executed when read by a browser.
id: no-eval-in-markdown
recommended: true
resolved: true
severity: error
then:
function: noEvalDescription
functionOptions:
pattern: eval\(
type: validation
no-http-verbs-in-path:
category:
description: Operations are the core of the contract, they define paths and HTTP methods. These rules check operations have been well constructed, looks for operationId, parameter, schema and return types in depth.
id: operations
name: Operations
description: Path segments must not contain an HTTP verb
formats:
- oas3
- oas3_1
- oas3_2
- oas2
given: $
howToFix: When HTTP verbs (get/post/put etc) are used in path segments, it muddies the semantics of REST and creates a confusing and inconsistent experience. It's highly recommended that verbs are not used in path segments. Replace those HTTP verbs with more meaningful nouns.
id: no-http-verbs-in-path
recommended: true
severity: warn
then:
function: noVerbsInPath
type: style
no-request-body:
category:
description: Operations are the core of the contract, they define paths and HTTP methods. These rules check operations have been well constructed, looks for operationId, parameter, schema and return types in depth.
id: operations
name: Operations
description: HTTP GET and DELETE should not accept request bodies
formats:
- oas3
- oas3_1
- oas3_2
given: $
howToFix: Remove 'requestBody' from HTTP GET and DELETE methods
id: no-request-body
recommended: true
severity: warn
then:
function: noRequestBody
type: style
no-script-tags-in-markdown:
category:
description: Validation rules make sure that certain characters or patterns have not been used that may cause issues when rendering in different types of applications.
id: validation
name: Validation
description: Markdown descriptions must not have `<script>` tags'
formats:
- oas3
- oas3_1
- oas3_2
- oas2
given: $
howToFix: Remove all references to '<script>' tags from the description. These can be used by malicious actors to load remote code if the spec is being parsed by a browser.
id: no-script-tags-in-markdown
recommended: true
resolved: true
severity: error
then:
function: noEvalDescription
functionOptions:
pattern: <script
type: validation
no-unnecessary-combinator:
category:
description: Schemas are how request bodies and response payloads are defined. They define the data going in and the data flowing out of an operation. These rules check for structural validity, checking types, checking required fields and validating correct use of structures.
id: schemas
name: Schemas
description: Schema combinators (allOf, anyOf, oneOf) with only one item should be replaced with the item directly.
formats:
- oas3
- oas3_1
- oas3_2
given: $
howToFix: Schema combinators (allOf, anyOf, oneOf) with only a single item are unnecessary and should be replaced with the item directly for cleaner, more readable schemas.
id: no-unnecessary-combinator
recommended: true
resolved: true
severity: warn
then:
function: oasUnnecessaryCombinator
type: style
oas-missing-type:
category:
description: Schemas are how request bodies and response payloads are defined. They define the data going in and the data flowing out of an operation. These rules check for structural validity, checking types, checking required fields and validating correct use of structures.
id: schemas
name: Schemas
description: All schemas and their properties should have a type field (unless using enum, const, or a composition)
formats:
- oas3
- oas3_1
- oas3_2
given: $
howToFix: 'Add a `type` field to all schemas and properties. Valid types are: string, number, integer, boolean, array, object, or null.'
id: oas-missing-type
recommended: true
severity: info
then:
function: missingType
type: validation
oas-schema-check:
category:
description: Schemas are how request bodies and response payloads are defined. They define the data going in and the data flowing out of an operation. These rules check for structural validity, checking types, checking required fields and validating correct use of structures.
id: schemas
name: Schemas
description: All document schemas must have a valid type defined
formats:
- oas3
- oas3_1
- oas3_2
given: $
howToFix: Make sure each schema has a value type defined. Without a type, the schema is useless
id: oas-schema-check
recommended: true
severity: error
then:
function: schemaTypeCheck
type: validation
oas2-anyOf:
category:
description: Schemas are how request bodies and response payloads are defined. They define the data going in and the data flowing out of an operation. These rules check for structural validity, checking types, checking required fields and validating correct use of structures.
id: schemas
name: Schemas
description: '`anyOf` was introduced in OpenAPI 3.0, cannot be used un OpenAPI 2 specs'
formats:
- oas2
given: $
howToFix: You can't use 'anyOf' in Swagger/OpenAPI 2 specs. It was added in version 3. You have to remove it
id: oas2-anyOf
recommended: true
severity: error
then:
function: oasPolymorphicAnyOf
type: validation
oas2-api-host:
category:
description: The info object contains licencing, contact, authorship details and more. Checks to confirm required details have been completed.
id: information
name: Contract Information
description: OpenAPI `host` must be present and a non-empty string
formats:
- oas2
given: $
howToFix: The 'host' value is missing. How is a user supposed to know where the API actually lives? The host is critical in order for consumers to be able to call the API. Add an API host!
id: oas2-api-host
recommended: true
severity: info
then:
field: host
function: truthy
type: style
oas2-api-schemes:
category:
description: The info object contains licencing, contact, authorship details and more. Checks to confirm required details have been completed.
id: information
name: Contract Information
description: OpenAPI host `schemes` must be present and non-empty array
formats:
- oas2
given: $
howToFix: Add an array of supported host 'schemes' to the root of the specification. These are the available API schemes (like https/http).
id: oas2-api-schemes
recommended: true
severity: warn
then:
field: schemes
function: schema
functionOptions:
forceValidation: true
schema:
items:
minItems: 1
type: string
type: array
uniqueItems: true
type: validation
oas2-discriminator:
category:
description: Schemas are how request bodies and response payloads are defined. They define the data going in and the data flowing out of an operation. These rules check for structural validity, checking types, checking required fields and validating correct use of structures.
id: schemas
name: Schemas
description: discriminators are used correctly in schemas
formats:
- oas2
given: $
howToFix: When using polymorphism, a discriminator should also be provided to allow tools to understand how to compose your models when generating code. Add a correct discriminator.
id: oas2-discriminator
recommended: true
resolved: true
severity: error
then:
function: oasDiscriminator
type: validation
oas2-host-not-example:
category:
description: The info object contains licencing, contact, authorship details and more. Checks to confirm required details have been completed.
id: information
name: Contract Information
description: Host URL should not point at example.com
formats:
- oas2
given: $.host
howToFix: Remove 'example.com' from the host URL, it's not going to work.
id: oas2-host-not-example
recommended: true
severity: warn
then:
function: pattern
functionOptions:
notMatch: example\.com
type: style
oas2-host-trailing-slash:
category:
description: The info object contains licencing, contact, authorship details and more. Checks to confirm required details have been completed.
id: information
name: Contract Information
description: Host URL should not contain a trailing slash
formats:
- oas2
given: $.host
howToFix: Remove the trailing slash from the host URL. This may cause some tools to incorrectly add a double slash to paths.
id: oas2-host-trailing-slash
recommended: true
severity: warn
then:
function: pattern
functionOptions:
notMatch: /$
type: style
oas2-oneOf:
category:
description: Schemas are how request bodies and response payloads are defined. They define the data going in and the data flowing out of an operation. These rules check for structural validity, checking types, checking required fields and validating correct use of structures.
id: schemas
name: Schemas
description: '`oneOf` was introduced in OpenAPI 3.0, cannot be used un OpenAPI 2 specs'
formats:
- oas2
given: $
howToFix: You can't use 'oneOf' in Swagger/OpenAPI 2 specs. It was added in version 3. You have to remove it
id: oas2-oneOf
recommended: true
severity: error
then:
function: oasPolymorphicOneOf
type: validation
oas2-operation-formData-consume-check:
category:
description: Operations are the core of the contract, they define paths and HTTP methods. These rules check operations have been well constructed, looks for operationId, parameter, schema and return types in depth.
id: operations
name: Operations
description: 'Operations with `in: formData` parameter must include `application/x-www-form-urlencoded` or `multipart/form-data` in their `consumes` property.'
formats:
- oas2
given: $
howToFix: When using 'formData', the parameter must include the correct mime-types. Make sure you use 'application/x-www-form-urlencoded' or 'multipart/form-data' as the 'consumes' value in your parameter.
id: oas2-operation-formData-consume-check
recommended: true
resolved: true
severity: warn
then:
function: oasOpFormDataConsumeCheck
type: validation
oas2-operation-security-defined:
category:
description: Security plays a central role in RESTful APIs. These rules make sure that the correct definitions have been used and put in the right places.
id: security
name: Security
description: '`security` values must match a scheme defined in securityDefinitions'
formats:
- oas2
given: $
howToFix: When defining security definitions for operations, you need to ensure they match the globally defined security schemes. Check $.securityDefinitions to make sure your values align.
id: oas2-operation-security-defined
recommended: true
resolved: true
severity: error
then:
function: oas2OpSecurityDefined
type: validation
oas2-parameter-description:
category:
description: Documentation is really important, in OpenAPI, just about everything can and should have a description. This set of rules checks for absent descriptions, poor quality descriptions (copy/paste), or short descriptions.
id: descriptions
name: Descriptions
description: Parameter description checks
formats:
- oas2
given: $
howToFix: All parameters should have a description. Descriptions are critical to understanding how an API works correctly. Please add a description to all parameters.
id: oas2-parameter-description
recommended: true
resolved: true
severity: warn
then:
function: oasParamDescriptions
type: style
oas2-schema:
category:
description: Validation rules make sure that certain characters or patterns have not been used that may cause issues when rendering in different types of applications.
id: validation
name: Validation
description: OpenAPI 2 specification is invalid
formats:
- oas2
given: $
howToFix: The schema isn't valid Swagger/OpenAPI 2. Check the errors for more details
id: oas2-schema
recommended: true
severity: error
then:
function: oasDocumentSchema
type: validation
oas2-unused-definition:
category:
description: Schemas are how request bodies and response payloads are defined. They define the data going in and the data flowing out of an operation. These rules check for structural validity, checking types, checking required fields and validating correct use of structures.
id: schemas
name: Schemas
description: Check for unused definitions and bad references
formats:
- oas2
given: $
howToFix: Orphaned components are not used by anything. You might have plans to use them later, or they could be older schemas that never got cleaned up. A clean spec is a happy spec. Prune your orphaned components.
id: oas2-unused-definition
recommended: true
severity: warn
then:
function: oasUnusedComponent
type: validation
oas3-api-servers:
category:
description: Validation rules make sure that certain characters or patterns have not been used that may cause issues when rendering in different types of applications.
id: validation
name: Validation
description: Check for valid API servers definition
formats:
- oas3
given: $
howToFix: Ensure server URIs are correct and valid, check the schemes, ensure descriptions are complete.
id: oas3-api-servers
recommended: true
severity: warn
then:
function: oasAPIServers
type: validation
oas3-example-external-check:
category:
description: Examples help consumers understand how API calls should look. They are really important for automated tooling for mocking and testing. These rules check examples have been added to component schemas, parameters and operations. These rules also check that examples match the schema and types provided.
id: examples
name: Examples
description: Examples cannot use both `value` and `externalValue` together.
formats:
- oas3
- oas3_1
- oas3_2
given: $
howToFix: Examples are critical for consumers to be able to understand schemas and models defined by the spec. Without examples, developers can't understand the type of data the API will return in real life. Examples are turned into mocks and can provide a rich testing capability for APIs. Add detailed examples everywhere!
id: oas3-example-external-check
recommended: true
severity: warn
then:
function: oasExampleExternal
type: validation
oas3-missing-example:
category:
description: Examples help consumers understand how API calls should look. They are really important for automated tooling for mocking and testing. These rules check examples have been added to component schemas, parameters and operations. These rules also check that examples match the schema and types provided.
id: examples
name: Examples
description: Ensure everything that can have an example, contains one
formats:
- oas3
- oas3_1
- oas3_2
given: $
howToFix: Examples are critical for consumers to be able to understand schemas and models defined by the spec. Without examples, developers can't understand the type of data the API will return in real life. Examples are turned into mocks and can provide a rich testing capability for APIs. Add detailed examples everywhere!
id: oas3-missing-example
recommended: true
severity: warn
then:
function: oasExampleMissing
type: validation
oas3-no-$ref-siblings:
category:
description: Schemas are how request bodies and response payloads are defined. They define the data going in and the data flowing out of an operation. These rules check for structural validity, checking types, checking required fields and validating correct use of structures.
id: schemas
name: Schemas
description: '`$ref` values cannot be placed next to other properties, except `description` and `summary`'
formats:
- oas3_1
given: $
howToFix: $ref values must not be placed next to sibling nodes, except `description` and `summary` nodes. This is wrong. remove all additional siblings!
id: oas3-no-$ref-siblings
recommended: true
severity: error
then:
function: oasRefSiblings
type: validation
oas3-operation-security-defined:
category:
description: Security plays a central role in RESTful APIs. These rules make sure that the correct definitions have been used and put in the right places.
id: security
name: Security
description: '`security` values must match a scheme defined in components.securitySchemes'
formats:
- oas3
- oas3_1
- oas3_2
given: $
howToFix: When defining security values for operations, you need to ensure they match the globally defined security schemes. Check $.components.securitySchemes to make sure your values align.
id: oas3-operation-security-defined
recommended: true
resolved: true
severity: error
then:
function: oasOpSecurityDefined
functionOptions:
schemesPath: $.components.securitySchemes
type: validation
oas3-parameter-description:
category:
description: Documentation is really important, in OpenAPI, just about everything can and should have a description. This set of rules checks for absent descriptions, poor quality descriptions (copy/paste), or short descriptions.
id: descriptions
name: Descriptions
description: Parameter description checks
formats:
- oas3
- oas3_1
- oas3_2
given: $
howToFix: All parameters should have a description. Descriptions are critical to understanding how an API works correctly. Please add a description to all parameters.
id: oas3-parameter-description
recommended: true
resolved: true
severity: warn
then:
function: oasParamDescriptions
type: style
oas3-schema:
category:
description: Schemas are how request bodies and response payloads are defined. They define the data going in and the data flowing out of an operation. These rules check for structural validity, checking types, checking required fields and validating correct use of structures.
id: schemas
name: Schemas
description: OpenAPI 3+ specification is invalid
formats:
- oas3
- oas3_1
- oas3_2
given: $
howToFix: The schema isn't valid OpenAPI 3. Check the errors for more details
id: oas3-schema
recommended: true
severity: error
then:
function: oasDocumentSchema
type: validation
oas3-unused-component:
category:
description: Schemas are how request bodies and response payloads are defined. They define the data going in and the data flowing out of an operation. These rules check for structural validity, checking types, checking required fields and validating correct use of structures.
id: schemas
name: Schemas
description: Check for unused components and bad references
formats:
- oas3
- oas3_1
- oas3_2
given: $
howToFix: Unused components / definitions are generally the result of the OpenAPI contract being updated without considering references. Another reference could have been updated, or an operation changed that no longer references this component. Remove this component from the spec, or re-link to it from another component or operation to fix the problem.
id: oas3-unused-component
recommended: true
severity: warn
then:
function: oasUnusedComponent
type: validation
oas3-valid-schema-example:
category:
description: Examples help consumers understand how API calls should look. They are really important for automated tooling for mocking and testing. These rules check examples have been added to component schemas, parameters and operations. These rules also check that examples match the schema and types provided.
id: examples
name: Examples
description: If an example has been used, check the schema is valid
formats:
- oas3
- oas3_1
- oas3_2
given: $
howToFix: Examples are critical for consumers to be able to understand schemas and models defined by the spec. Without examples, developers can't understand the type of data the API will return in real life. Examples are turned into mocks and can provide a rich testing capability for APIs. Add detailed examples everywhere!
id: oas3-valid-schema-example
recommended: true
severity: warn
then:
function: oasExampleSchema
type: validation
operation-description:
category:
description: Documentation is really important, in OpenAPI, just about everything can and should have a description. This set of rules checks for absent descriptions, poor quality descriptions (copy/paste), or short descriptions.
id: descriptions
name: Descriptions
description: Operation description checks
formats:
- oas3
- oas3_1
- oas3_2
- oas2
given: $
howToFix: All operations must have a description. Descriptions explain how the operation works, and how users should use it and what to expect. Operation descriptions make up the bulk of API documentation. so please, add a description!
id: operation-description
recommended: true
resolved: true
severity: warn
then:
function: oasDescriptions
functionOptions:
minWords: "1"
type: validation
operation-operationId:
category:
description: Operations are the core of the contract, they define paths and HTTP methods. These rules check operations have been well constructed, looks for operationId, parameter, schema and return types in depth.
id: operations
name: Operations
description: Every operation must contain an `operationId`.
formats:
- oas3
- oas3_1
- oas3_2
- oas2
given: $
howToFix: Every single operation needs an operationId. It's a critical requirement to be able to identify each individual operation uniquely. Please add an operationId to the operation.
id: operation-operationId
recommended: true
severity: error
then:
function: oasOpId
type: validation
operation-operationId-unique:
category:
description: Operations are the core of the contract, they define paths and HTTP methods. These rules check operations have been well constructed, looks for operationId, parameter, schema and return types in depth.
id: operations
name: Operations
description: Every operation must have unique `operationId`.
formats:
- oas3
- oas3_1
- oas3_2
- oas2
given: $.paths
howToFix: An operationId needs to be unique, there can't be any duplicates in the document, you can't re-use them. Make sure the ID used for this operation is unique.
id: operation-operationId-unique
recommended: true
resolved: true
severity: error
then:
function: oasOpIdUnique
type: validation
operation-operationId-valid-in-url:
category:
description: Operations are the core of the contract, they define paths and HTTP methods. These rules check operations have been well constructed, looks for operationId, parameter, schema and return types in depth.
id: operations
name: Operations
description: OperationId must use URL friendly characters
formats:
- oas3
- oas3_1
- oas3_2
- oas2
given: $.paths[*][*]
howToFix: An operationId is critical to correct code generation and operation identification. The operationId should really be designed in a way to make it friendly when used as part of a URL. Remove non-standard URL characters.
id: operation-operationId-valid-in-url
recommended: true
resolved: true
severity: error
then:
field: operationId
function: pattern
functionOptions:
match: ^[A-Za-z0-9-._~:/?#\[\]@!\$&'()*+,;=]*$
type: validation
operation-parameters:
category:
description: Operations are the core of the contract, they define paths and HTTP methods. These rules check operations have been well constructed, looks for operationId, parameter, schema and return types in depth.
id: operations
name: Operations
description: Operation parameters are unique and non-repeating.
formats:
- oas3
- oas3_1
- oas3_2
- oas2
given: $.paths
howToFix: Make sure that all the operation parameters are unique and non-repeating, don't duplicate names, don'tre-use parameter names in the same operation.
id: operation-parameters
recommended: true
resolved: true
severity: error
then:
function: oasOpParams
type: validation
operation-success-response:
category:
description: Operations are the core of the contract, they define paths and HTTP methods. These rules check operations have been well constructed, looks for operationId, parameter, schema and return types in depth.
id: operations
name: Operations
description: Operation must have at least one `2xx` or a `3xx` response.
formats:
- oas3
- oas3_1
- oas3_2
- oas2
given: $
howToFix: Make sure that your operation returns a 'success' response via 2xx or 3xx response code. An API consumer will always expect a success response
id: operation-success-response
recommended: true
resolved: true
severity: warn
then:
field: responses
function: oasOpSuccessResponse
type: style
operation-tag-defined:
category:
description: Tags are used as meta-data for operations. They are mainly used by tooling as a taxonomy mechanism to build navigation, search and more. Tags are important as they help consumers navigate the contract when using documentation, testing, code generation or analysis tools.
id: tags
name: Tags
description: Operation tags must be defined in global tags.
formats:
- oas3
- oas3_1
- oas3_2
- oas2
given: $
howToFix: This tag has not been defined in the global scope, you should always ensure that any tags used in operations, are defined globally in the root 'tags' definition.
id: operation-tag-defined
recommended: true
resolved: true
severity: warn
then:
function: oasTagDefined
type: validation
operation-tags:
category:
description: Tags are used as meta-data for operations. They are mainly used by tooling as a taxonomy mechanism to build navigation, search and more. Tags are important as they help consumers navigate the contract when using documentation, testing, code generation or analysis tools.
id: tags
name: Tags
description: Operation `tags` are missing/empty
formats:
- oas3
- oas3_1
- oas3_2
- oas2
given: $
howToFix: Operations use tags to define the domain(s) they are apart of. Generally a single tag per operation is used, however some tools use multiple tags. The point is that you need tags! Add some tags to the operation that match the globally available ones.
id: operation-tags
recommended: true
resolved: true
severity: warn
then:
function: oasOperationTags
type: validation
path-declarations-must-exist:
category:
description: Operations are the core of the contract, they define paths and HTTP methods. These rules check operations have been well constructed, looks for operationId, parameter, schema and return types in depth.
id: operations
name: Operations
description: Path parameter declarations must not be empty ex. `/api/{}` is invalid
formats:
- oas3
- oas3_1
- oas3_2
- oas2
given: $.paths
howToFix: Paths define the endpoint for operations. Without paths, there is no API. You need to add 'paths' to the root of the specification.
id: path-declarations-must-exist
recommended: true
resolved: true
severity: error
then:
function: pattern
functionOptions:
notMatch: '{}'
type: validation
path-item-refs:
category:
description: Operations are the core of the contract, they define paths and HTTP methods. These rules check operations have been well constructed, looks for operationId, parameter, schema and return types in depth.
id: operations
name: Operations
description: Path items should not use references ($ref) values. They are technically not allowed.
formats:
- oas3
- oas3_1
- oas3_2
given: $
howToFix: Path items should not use references for defining operations. It's technically allowed, but not great style
id: path-item-refs
recommended: true
severity: info
then:
function: pathItemReferences
type: validation
path-keys-no-trailing-slash:
category:
description: Operations are the core of the contract, they define paths and HTTP methods. These rules check operations have been well constructed, looks for operationId, parameter, schema and return types in depth.
id: operations
name: Operations
description: Path must not end with a slash
formats:
- oas3
- oas3_1
- oas3_2
- oas2
given: $.paths
howToFix: Paths should not end with a trailing slash, it can confuse tooling and isn't valid as a path Remove the trailing slash from the path.
id: path-keys-no-trailing-slash
recommended: true
resolved: true
severity: warn
then:
function: pattern
functionOptions:
notMatch: .+\/$
type: validation
path-not-include-query:
category:
description: Operations are the core of the contract, they define paths and HTTP methods. These rules check operations have been well constructed, looks for operationId, parameter, schema and return types in depth.
id: operations
name: Operations
description: Path must not include query string
formats:
- oas3
- oas3_1
- oas3_2
- oas2
given: $.paths
howToFix: Query strings are defined as parameters for an operation, they should not be included in the path Please remove it and correctly define as a parameter.
id: path-not-include-query
recommended: true
resolved: true
severity: error
then:
function: pattern
functionOptions:
notMatch: \?
type: validation
path-params:
category:
description: Operations are the core of the contract, they define paths and HTTP methods. These rules check operations have been well constructed, looks for operationId, parameter, schema and return types in depth.
id: operations
name: Operations
description: Path parameters must be defined and valid.
formats:
- oas3
- oas3_1
- oas3_2
given: $
howToFix: Path parameters need to match up with the parameters defined for the path, or in an operation that sits under that path. Make sure variable names match up and are defined correctly.
id: path-params
recommended: true
resolved: true
severity: error
then:
function: oasPathParam
type: validation
paths-kebab-case:
category:
description: Operations are the core of the contract, they define paths and HTTP methods. These rules check operations have been well constructed, looks for operationId, parameter, schema and return types in depth.
id: operations
name: Operations
description: Path segments must only use kebab-case (no underscores or uppercase)
formats:
- oas3
- oas3_1
- oas3_2
- oas2
given: $
howToFix: Path segments should not contain any uppercase letters, punctuation or underscores. The only valid way to separate words in a segment, is to use a hyphen '-'. The elements that are violating the rule are highlighted in the violation description. These are the elements that need to change.
id: paths-kebab-case
recommended: true
severity: warn
then:
function: pathsKebabCase
type: validation
typed-enum:
category:
description: Schemas are how request bodies and response payloads are defined. They define the data going in and the data flowing out of an operation. These rules check for structural validity, checking types, checking required fields and validating correct use of structures.
id: schemas
name: Schemas
description: Enum values must respect the specified type
formats:
- oas3
- oas3_1
- oas3_2
- oas2
given: $
howToFix: Enum values lock down the number of variable inputs a parameter or schema can have. The problem here is that the Enum defined, does not match the specified type. Fix the type!
id: typed-enum
recommended: true
resolved: true
severity: warn
then:
function: typedEnum
type: validation

1
test/vacuum.conf.yaml Normal file
View File

@@ -0,0 +1 @@
ruleset: "./vacuum-rules.yaml"

101
test/yarn.lock
View File

@@ -214,6 +214,14 @@
resolved "https://registry.yarnpkg.com/@pkgjs/parseargs/-/parseargs-0.11.0.tgz#a77ea742fab25775145434eb1d2328cf5013ac33"
integrity sha512-+1VkjdD0QBLPodGrJUeqarH8VAIvQODIbwh9XpP5Syisf7YoQgsJKPNFoqqLQlu+VQ/tVSshMR6loPMn8U+dPg==
"@quobix/vacuum@^0.19.4":
version "0.19.4"
resolved "https://registry.yarnpkg.com/@quobix/vacuum/-/vacuum-0.19.4.tgz#1250269268aa0838e503ea97836a98d7c9756bf1"
integrity sha512-+riEvta1fR2loK//bpdPOVs5AgE8F26RrKe6/oGjapAKVB/OOcqE88S+TSe/yeQbmj03QLi5EX3ZmrL9n0qyDg==
dependencies:
node-fetch "^3.2.10"
tar "^6.1.11"
"@types/color-name@^1.1.1":
version "1.1.1"
resolved "https://registry.yarnpkg.com/@types/color-name/-/color-name-1.1.1.tgz#1c1261bbeaa10a8055bbc5d8ab84b7b2afc846a0"
@@ -557,6 +565,11 @@ chokidar@^4.0.1:
dependencies:
readdirp "^4.0.1"
chownr@^2.0.0:
version "2.0.0"
resolved "https://registry.yarnpkg.com/chownr/-/chownr-2.0.0.tgz#15bfbe53d2eab4cf70f18a8cd68ebe5b3cb1dece"
integrity sha512-bIomtDF5KGpdogkLd9VspvFzk9KfpyyGlS8YFVZl7TGPBHL5snIOnxeshwVgPteQ9b4Eydl+pVbIyE1DcvCWgQ==
ci-info@^4.1.0:
version "4.2.0"
resolved "https://registry.yarnpkg.com/ci-info/-/ci-info-4.2.0.tgz#cbd21386152ebfe1d56f280a3b5feccbd96764c7"
@@ -733,6 +746,11 @@ dashdash@^1.12.0:
dependencies:
assert-plus "^1.0.0"
data-uri-to-buffer@^4.0.0:
version "4.0.1"
resolved "https://registry.yarnpkg.com/data-uri-to-buffer/-/data-uri-to-buffer-4.0.1.tgz#d8feb2b2881e6a4f58c2e08acfd0e2834e26222e"
integrity sha512-0R9ikRb668HB7QDxT1vkpuUBtqc53YyAwMwGeUFKRojY/NWKvdZ+9UYtRfGmhqNbRkTSVpMbmyhXipFFv2cb/A==
dayjs@^1.10.4:
version "1.11.7"
resolved "https://registry.yarnpkg.com/dayjs/-/dayjs-1.11.7.tgz#4b296922642f70999544d1144a2c25730fce63e2"
@@ -1111,6 +1129,14 @@ fd-slicer@~1.1.0:
dependencies:
pend "~1.2.0"
fetch-blob@^3.1.2, fetch-blob@^3.1.4:
version "3.2.0"
resolved "https://registry.yarnpkg.com/fetch-blob/-/fetch-blob-3.2.0.tgz#f09b8d4bbd45adc6f0c20b7e787e793e309dcce9"
integrity sha512-7yAQpD2UMJzLi1Dqv7qFYnPbaPx7ZfFK6PiIxQ4PfkGPyNyl2Ugx+a/umUonmKqjhM4DnfbMvdX6otXq83soQQ==
dependencies:
node-domexception "^1.0.0"
web-streams-polyfill "^3.0.3"
figures@^3.2.0:
version "3.2.0"
resolved "https://registry.yarnpkg.com/figures/-/figures-3.2.0.tgz#625c18bd293c604dc4a8ddb2febf0c88341746af"
@@ -1187,6 +1213,13 @@ form-data@~4.0.0:
combined-stream "^1.0.8"
mime-types "^2.1.12"
formdata-polyfill@^4.0.10:
version "4.0.10"
resolved "https://registry.yarnpkg.com/formdata-polyfill/-/formdata-polyfill-4.0.10.tgz#24807c31c9d402e002ab3d8c720144ceb8848423"
integrity sha512-buewHzMvYL29jdeQTVILecSaZKnt/RJWjoZCF5OW60Z67/GmSLBkOFM7qh1PI3zFNtJbaZL5eQu1vLfazOwj4g==
dependencies:
fetch-blob "^3.1.2"
fs-extra@^9.1.0:
version "9.1.0"
resolved "https://registry.yarnpkg.com/fs-extra/-/fs-extra-9.1.0.tgz#5954460c764a8da2094ba3554bf839e6b9a7c86d"
@@ -1197,6 +1230,13 @@ fs-extra@^9.1.0:
jsonfile "^6.0.1"
universalify "^2.0.0"
fs-minipass@^2.0.0:
version "2.1.0"
resolved "https://registry.yarnpkg.com/fs-minipass/-/fs-minipass-2.1.0.tgz#7f5036fdbf12c63c169190cbe4199c852271f9fb"
integrity sha512-V/JgOLFCS+R6Vcq0slCuaeWEdNC3ouDlJMNIsacH2VtALiu9mV4LPrHc5cDl8k5aw6J8jwgWWpiTo5RYhmIzvg==
dependencies:
minipass "^3.0.0"
function-bind@^1.1.2:
version "1.1.2"
resolved "https://registry.yarnpkg.com/function-bind/-/function-bind-1.1.2.tgz#2c02d864d97f3ea6c8830c464cbd11ab6eab7a1c"
@@ -1668,11 +1708,36 @@ minimist@^1.2.8:
resolved "https://registry.yarnpkg.com/minimist/-/minimist-1.2.8.tgz#c1a464e7693302e082a075cee0c057741ac4772c"
integrity sha512-2yyAR8qBkN3YuheJanUpWC5U3bb5osDywNB8RzDVlDwDHbocAJveqqj1u8+SVD7jkWT4yvsHCpWqqWqAxb0zCA==
minipass@^3.0.0:
version "3.3.6"
resolved "https://registry.yarnpkg.com/minipass/-/minipass-3.3.6.tgz#7bba384db3a1520d18c9c0e5251c3444e95dd94a"
integrity sha512-DxiNidxSEK+tHG6zOIklvNOwm3hvCrbUrdtzY74U6HKTJxvIDfOUL5W5P2Ghd3DTkhhKPYGqeNUIh5qcM4YBfw==
dependencies:
yallist "^4.0.0"
minipass@^5.0.0:
version "5.0.0"
resolved "https://registry.yarnpkg.com/minipass/-/minipass-5.0.0.tgz#3e9788ffb90b694a5d0ec94479a45b5d8738133d"
integrity sha512-3FnjYuehv9k6ovOEbyOswadCDPX1piCfhV8ncmYtHOjuPwylVWsghTLo7rabjC3Rx5xD4HDx8Wm1xnMF7S5qFQ==
"minipass@^5.0.0 || ^6.0.2 || ^7.0.0", minipass@^7.1.2:
version "7.1.2"
resolved "https://registry.yarnpkg.com/minipass/-/minipass-7.1.2.tgz#93a9626ce5e5e66bd4db86849e7515e92340a707"
integrity sha512-qOOzS1cBTWYF4BH8fVePDBOO9iptMnGUEZwNc/cMWnTV2nVLZ7VoNWEPHkYczZA0pdoA7dl6e7FL659nX9S2aw==
minizlib@^2.1.1:
version "2.1.2"
resolved "https://registry.yarnpkg.com/minizlib/-/minizlib-2.1.2.tgz#e90d3466ba209b932451508a11ce3d3632145931"
integrity sha512-bAxsR8BVfj60DWXHE3u30oHzfl4G7khkSuPW+qvpd7jFRHm7dLxOjUk1EHACJ/hxLY8phGJ0YhYHZo7jil7Qdg==
dependencies:
minipass "^3.0.0"
yallist "^4.0.0"
mkdirp@^1.0.3:
version "1.0.4"
resolved "https://registry.yarnpkg.com/mkdirp/-/mkdirp-1.0.4.tgz#3eb5ed62622756d79a5f0e2a221dfebad75c2f7e"
integrity sha512-vVqVZQyf3WLx2Shd0qJ9xuvqgAyKPLAiqITEtqW0oIUjzo3PePDd6fW9iFz30ef7Ysp/oiWqbhszeGWW2T6Gzw==
mkdirp@^3.0.0:
version "3.0.1"
resolved "https://registry.yarnpkg.com/mkdirp/-/mkdirp-3.0.1.tgz#e44e4c5607fb279c168241713cc6e0fea9adcb50"
@@ -1730,6 +1795,20 @@ natural-compare@^1.4.0:
resolved "https://registry.yarnpkg.com/natural-compare/-/natural-compare-1.4.0.tgz#4abebfeed7541f2c27acfb29bdbbd15c8d5ba4f7"
integrity sha1-Sr6/7tdUHywnrPspvbvRXI1bpPc=
node-domexception@^1.0.0:
version "1.0.0"
resolved "https://registry.yarnpkg.com/node-domexception/-/node-domexception-1.0.0.tgz#6888db46a1f71c0b76b3f7555016b63fe64766e5"
integrity sha512-/jKZoMpw0F8GRwl4/eLROPA3cfcXtLApP0QzLmUT/HuPCZWyB7IY9ZrMeKw2O/nFIqPQB3PVM9aYm0F312AXDQ==
node-fetch@^3.2.10:
version "3.3.2"
resolved "https://registry.yarnpkg.com/node-fetch/-/node-fetch-3.3.2.tgz#d1e889bacdf733b4ff3b2b243eb7a12866a0b78b"
integrity sha512-dRB78srN/l6gqWulah9SrxeYnxeddIG30+GOqK/9OlLVyLg3HPnr6SqOWTWOXKRwC2eGYCkZ59NNuSgvSrpgOA==
dependencies:
data-uri-to-buffer "^4.0.0"
fetch-blob "^3.1.4"
formdata-polyfill "^4.0.10"
npm-run-path@^4.0.0:
version "4.0.1"
resolved "https://registry.yarnpkg.com/npm-run-path/-/npm-run-path-4.0.1.tgz#b7ecd1e5ed53da8e37a55e1c2269e0b97ed748ea"
@@ -2197,6 +2276,18 @@ supports-color@^8.1.1:
dependencies:
has-flag "^4.0.0"
tar@^6.1.11:
version "6.2.1"
resolved "https://registry.yarnpkg.com/tar/-/tar-6.2.1.tgz#717549c541bc3c2af15751bea94b1dd068d4b03a"
integrity sha512-DZ4yORTwrbTj/7MZYq2w+/ZFdI6OZ/f9SFHR+71gIVUZhOQPHzVCLpvRnPgyaMpfWxxk/4ONva3GQSyNIKRv6A==
dependencies:
chownr "^2.0.0"
fs-minipass "^2.0.0"
minipass "^5.0.0"
minizlib "^2.1.1"
mkdirp "^1.0.3"
yallist "^4.0.0"
throttleit@^1.0.0:
version "1.0.0"
resolved "https://registry.yarnpkg.com/throttleit/-/throttleit-1.0.0.tgz#9e785836daf46743145a5984b6268d828528ac6c"
@@ -2315,6 +2406,11 @@ verror@1.10.0:
core-util-is "1.0.2"
extsprintf "^1.2.0"
web-streams-polyfill@^3.0.3:
version "3.3.3"
resolved "https://registry.yarnpkg.com/web-streams-polyfill/-/web-streams-polyfill-3.3.3.tgz#2073b91a2fdb1fbfbd401e7de0ac9f8214cecb4b"
integrity sha512-d2JWLCivmZYTSIoge9MsgFCZrt571BikcWGYkjC1khllbTeDlGqZ2D8vD8E/lJa8WGWbb7Plm8/XJYV7IJHZZw==
which@^2.0.1:
version "2.0.2"
resolved "https://registry.yarnpkg.com/which/-/which-2.0.2.tgz#7c6a8dd0a636a0327e10b59c9286eee93f3f51b1"
@@ -2388,6 +2484,11 @@ y18n@^5.0.5:
resolved "https://registry.yarnpkg.com/y18n/-/y18n-5.0.8.tgz#7f4934d0f7ca8c56f95314939ddcd2dd91ce1d55"
integrity sha512-0pfFzegeDWJHJIAmTLRP2DwHjdF5s7jo9tuztdQxAhINCdvS+3nGINqPd00AphqJR/0LhANUS6/+7SCb98YOfA==
yallist@^4.0.0:
version "4.0.0"
resolved "https://registry.yarnpkg.com/yallist/-/yallist-4.0.0.tgz#9bb92790d9c0effec63be73519e11a35019a3a72"
integrity sha512-3wdGidZyq5PB084XLES5TpOSRA3wjXAlIWMhum2kRcv/41Sn2emQ0dycQW4uZXLejwKvg6EsvbdlVL+FYEct7A==
yargs-parser@^21.1.1:
version "21.1.1"
resolved "https://registry.yarnpkg.com/yargs-parser/-/yargs-parser-21.1.1.tgz#9096bceebf990d21bb31fa9516e0ede294a77d35"