openapi-semantic-validator
TypeScript icon, indicating that this package has built-in type declarations

0.5.0 • Public • Published

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 build
yarn test

License

MIT

Readme

Keywords

none

Package Sidebar

Install

npm i openapi-semantic-validator

Weekly Downloads

96

Version

0.5.0

License

MIT

Unpacked Size

80 kB

Total Files

32

Last publish

Collaborators

  • mhassan1