ReadMe · API Governance Rules

ReadMe API Rules

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

9 Rules error 5 warn 4

View Rules File View on GitHub

Rule Categories

readme

Rules

error

readme-info-title

API title must be present and start with "ReadMe".

$.info.title

warn

readme-info-contact

API info must include a contact block.

$.info

warn

readme-server-url

Server URLs should point to api.readme.com or metrics.readme.io.

$.servers[*].url

error

readme-bearer-auth

The ReadMe API must declare bearer auth.

$.components.securitySchemes

error

readme-tag-title-case

Tags must be Title Case.

$.tags[*].name

warn

readme-operation-summary-title-case

Operation summaries must use Title Case.

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

error

readme-operation-tags-required

Every operation must have at least one tag.

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

error

readme-operation-responses-required

Every operation must define at least one response.

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

warn

readme-no-trailing-slash

Paths must not end with a trailing slash.

$.paths

Spectral Ruleset

extends:
  - spectral:oas
formats:
  - oas3_1
rules:
  readme-info-title:
    description: API title must be present and start with "ReadMe".
    given: $.info.title
    severity: error
    then:
      function: pattern
      functionOptions:
        match: '^ReadMe'
  readme-info-contact:
    description: API info must include a contact block.
    given: $.info
    severity: warn
    then:
      field: contact
      function: truthy
  readme-server-url:
    description: Server URLs should point to api.readme.com or metrics.readme.io.
    given: $.servers[*].url
    severity: warn
    then:
      function: pattern
      functionOptions:
        match: '(api\.readme\.com|metrics\.readme\.io|dash\.readme\.io)'
  readme-bearer-auth:
    description: The ReadMe API must declare bearer auth.
    given: $.components.securitySchemes
    severity: error
    then:
      field: bearerAuth
      function: truthy
  readme-tag-title-case:
    description: Tags must be Title Case.
    given: $.tags[*].name
    severity: error
    then:
      function: pattern
      functionOptions:
        match: '^[A-Z][A-Za-z0-9]*(\s[A-Z][A-Za-z0-9]*)*$'
  readme-operation-summary-title-case:
    description: Operation summaries must use Title Case.
    given: $.paths[*][get,post,put,patch,delete].summary
    severity: warn
    then:
      function: pattern
      functionOptions:
        match: '^[A-Z][A-Za-z0-9]*(\s[A-Z][A-Za-z0-9]*)*$'
  readme-operation-tags-required:
    description: Every operation must have at least one tag.
    given: $.paths[*][get,post,put,patch,delete]
    severity: error
    then:
      field: tags
      function: truthy
  readme-operation-responses-required:
    description: Every operation must define at least one response.
    given: $.paths[*][get,post,put,patch,delete]
    severity: error
    then:
      field: responses
      function: truthy
  readme-no-trailing-slash:
    description: Paths must not end with a trailing slash.
    given: $.paths
    severity: warn
    then:
      function: pattern
      functionOptions:
        notMatch: '/$'