openapi-semantic-validator v0.4.0

OpenAPI Semantic Validator

Perform semantic validation on an OpenAPI specification, just like Swagger Editor!

Purpose

Swagger Editor performs both structural (schema) and semantic (spec) validation of OpenAPI specifications. While swagger-parser performs structural validation, it does not (yet) support semantic validation:

Note: Validating against the OpenAPI 3.0 Specification is not (yet) supported. For now, the validate.spec option is ignored if your API is in OpenAPI 3.0 format.

-- swagger-parser docs

Once swagger-parser adds support for semantic validation, this package will be deprecated.

This package performs semantic validation by executing the validators from the swagger-editor package. It does not parse OpenAPI specifications or perform structural validation; use swagger-parser for that.

Validation Examples

Structural

NOTE: This package does not perform structural validation; use swagger-parser for that.

• should have required property 'X'
• should NOT have additional properties
• etc.

Semantic

• Operations must have unique operationIds
• Path parameter "X" must have the corresponding {X} segment in the "Y" path
• etc.

Installation

yarn add openapi-semantic-validator

Usage

This package should be used alongside swagger-parser, which provides structural validation:

const SwaggerParser = require('@apidevtools/swagger-parser')
const { validateOpenapiSemantics } = require('openapi-semantic-validator')

// parse and validate structure
const spec = await SwaggerParser.validate('openapi.yml')

// validate semantics
try {
  await validateOpenapiSemantics(spec)
  log('no semantic errors!')
} catch (err) {
  log(`semantic errors: ${JSON.stringify(err.semanticErrors)}`)
}

API

• validateOpenapiSemantics(spec)
  • Validates an OpenAPI specification
  • Inputs:
    • spec: Parsed OpenAPI specification
  • Returns: Promise
    • If no semantic errors are found, resolves
    • If semantic errors are found, rejects with an Error object containing a semanticErrors property; this is an array of objects containing:
      • level: 'error' | 'warning'
      • message: string
      • path: string[]

Development

yarn
yarn test

License

MIT