SwaggerHub · API Governance Rules

SwaggerHub API Rules

Spectral linting rules defining API design standards and conventions for SwaggerHub.

9 Rules error 4 warn 5

View Rules File View on GitHub

Rule Categories

swaggerhub

Rules

warn

swaggerhub-operations-have-tags

All SwaggerHub API operations must have at least one tag

$.paths[*][get,post,put,patch,delete]

error

swaggerhub-operations-have-summaries

All SwaggerHub API operations must have a summary

$.paths[*][get,post,put,patch,delete]

warn

swaggerhub-summaries-title-case

SwaggerHub operation summaries must use Title Case

$.paths[*][get,post,put,patch,delete].summary

error

swaggerhub-operations-have-operation-ids

All SwaggerHub API operations must have an operationId

$.paths[*][get,post,put,patch,delete]

warn

swaggerhub-operations-have-descriptions

All SwaggerHub API operations should have a description

$.paths[*][get,post,put,patch,delete]

error

swaggerhub-path-params-required

Path parameters must be marked as required

$.paths[*][*].parameters[?(@.in == 'path')]

warn

swaggerhub-schemas-have-descriptions

All component schemas must have a description

$.components.schemas[*]

warn

swaggerhub-responses-have-descriptions

All response objects must have a description

$.paths[*][*].responses[*]

error

swaggerhub-security-scheme-defined

API must define at least one security scheme

$.components

Spectral Ruleset

extends: spectral:oas
rules:

  swaggerhub-operations-have-tags:
    description: All SwaggerHub API operations must have at least one tag
    severity: warn
    given: "$.paths[*][get,post,put,patch,delete]"
    then:
      field: tags
      function: truthy

  swaggerhub-operations-have-summaries:
    description: All SwaggerHub API operations must have a summary
    severity: error
    given: "$.paths[*][get,post,put,patch,delete]"
    then:
      field: summary
      function: truthy

  swaggerhub-summaries-title-case:
    description: SwaggerHub operation summaries must use Title Case
    severity: warn
    given: "$.paths[*][get,post,put,patch,delete].summary"
    then:
      function: pattern
      functionOptions:
        match: "^[A-Z][a-zA-Z0-9]*([ ][A-Z][a-zA-Z0-9]*)*$"

  swaggerhub-operations-have-operation-ids:
    description: All SwaggerHub API operations must have an operationId
    severity: error
    given: "$.paths[*][get,post,put,patch,delete]"
    then:
      field: operationId
      function: truthy

  swaggerhub-operations-have-descriptions:
    description: All SwaggerHub API operations should have a description
    severity: warn
    given: "$.paths[*][get,post,put,patch,delete]"
    then:
      field: description
      function: truthy

  swaggerhub-path-params-required:
    description: Path parameters must be marked as required
    severity: error
    given: "$.paths[*][*].parameters[?(@.in == 'path')]"
    then:
      field: required
      function: truthy

  swaggerhub-schemas-have-descriptions:
    description: All component schemas must have a description
    severity: warn
    given: "$.components.schemas[*]"
    then:
      field: description
      function: truthy

  swaggerhub-responses-have-descriptions:
    description: All response objects must have a description
    severity: warn
    given: "$.paths[*][*].responses[*]"
    then:
      field: description
      function: truthy

  swaggerhub-security-scheme-defined:
    description: API must define at least one security scheme
    severity: error
    given: "$.components"
    then:
      field: securitySchemes
      function: truthy