@swagger-api/apidom-parser-adapter-openapi-yaml-3-1

What is @swagger-api/apidom-parser-adapter-openapi-yaml-3-1?

@swagger-api/apidom-parser-adapter-openapi-yaml-3-1 is an npm package designed to parse OpenAPI 3.1 YAML documents. It is part of the ApiDOM ecosystem, which provides tools for working with API descriptions in various formats. This package specifically focuses on handling OpenAPI 3.1 YAML documents, allowing developers to parse, manipulate, and validate these documents within their applications.

What are @swagger-api/apidom-parser-adapter-openapi-yaml-3-1's main functionalities?

Parsing OpenAPI 3.1 YAML Documents

This feature allows you to parse an OpenAPI 3.1 YAML document into a JavaScript object. The code sample demonstrates how to use the `parse` function to convert a YAML string into a parsed object.

const { parse } = require('@swagger-api/apidom-parser-adapter-openapi-yaml-3-1');

const yamlDocument = `
openapi: 3.1.0
info:
  title: Sample API
  version: 1.0.0
paths:
  /example:
    get:
      summary: Example endpoint
      responses:
        '200':
          description: Successful response
`;

parse(yamlDocument).then((parsed) => {
  console.log(parsed);
}).catch((error) => {
  console.error('Error parsing YAML:', error);
});

Validating OpenAPI 3.1 YAML Documents

This feature allows you to validate an OpenAPI 3.1 YAML document. The code sample demonstrates how to use the `validate` function to check if a YAML string conforms to the OpenAPI 3.1 specification.

const { validate } = require('@swagger-api/apidom-parser-adapter-openapi-yaml-3-1');

const yamlDocument = `
openapi: 3.1.0
info:
  title: Sample API
  version: 1.0.0
paths:
  /example:
    get:
      summary: Example endpoint
      responses:
        '200':
          description: Successful response
`;

validate(yamlDocument).then((result) => {
  if (result.valid) {
    console.log('YAML document is valid');
  } else {
    console.error('Validation errors:', result.errors);
  }
}).catch((error) => {
  console.error('Error validating YAML:', error);
});

Other packages similar to @swagger-api/apidom-parser-adapter-openapi-yaml-3-1

swagger-parser

swagger-parser is a powerful tool for parsing, validating, and dereferencing Swagger and OpenAPI definitions. It supports both JSON and YAML formats and can handle OpenAPI versions 2.0 and 3.0. Compared to @swagger-api/apidom-parser-adapter-openapi-yaml-3-1, swagger-parser offers broader support for different OpenAPI versions but does not specifically target OpenAPI 3.1.

openapi-parser

openapi-parser is a lightweight library for parsing and validating OpenAPI documents. It supports OpenAPI 3.0 and 3.1 and can handle both JSON and YAML formats. Compared to @swagger-api/apidom-parser-adapter-openapi-yaml-3-1, openapi-parser provides similar functionality but is not part of the ApiDOM ecosystem.

redoc

redoc is a popular tool for generating API documentation from OpenAPI definitions. It supports OpenAPI 2.0, 3.0, and 3.1 and can handle both JSON and YAML formats. While redoc focuses on documentation generation, it also includes parsing and validation capabilities. Compared to @swagger-api/apidom-parser-adapter-openapi-yaml-3-1, redoc offers a more comprehensive solution for API documentation but is not solely focused on parsing.

README

@swagger-api/apidom-parser-adapter-openapi-yaml-3-1

@swagger-api/apidom-parser-adapter-openapi-yaml-3-1 is a parser adapter for the OpenAPI 3.1.0 specification in YAML format. Under the hood this adapter uses apidom-parser-adapter-yaml-1-2 to parse a source string into generic ApiDOM in base ApiDOM namespace which is then refracted with OpenAPI 3.1.0 Refractors.

Installation

After prerequisites for installing this package are satisfied, you can install it via npm CLI by running the following command:

 $ npm install @swagger-api/apidom-parser-adapter-openapi-yaml-3-1

Parser adapter API

This parser adapter is fully compatible with parser adapter interface required by @swagger-api/apidom-parser and implements all required properties.

mediaTypes

Defines list of media types that this parser adapter recognizes.

[
  'application/vnd.oai.openapi;version=3.1.0',
  'application/vnd.oai.openapi+yaml;version=3.1.0',
]

detect

Detection is based on a regular expression matching required OpenAPI 3.1.0 specification symbols in YAML format.

namespace

This adapter exposes an instance of OpenAPI 3.1.0 ApiDOM namespace.

parse

parse function consumes various options as a second argument. Here is a list of these options:

Option	Type	Default	Description
specObj	Object	Specification Object	This specification object drives the YAML AST transformation to OpenAPI 3.1.0 ApiDOM namespace.
sourceMap	Boolean	false	Indicate whether to generate source maps.
refractorOpts	Object	{}	Refractor options are passed to refractors during refracting phase.

All unrecognized arbitrary options will be ignored.

Usage

This parser adapter can be used directly or indirectly via apidom-parser.

Direct usage

During direct usage you don't need to provide mediaType as the parse function is already pre-bound with supported media types.

import { parse, detect } from '@swagger-api/apidom-parser-adapter-openapi-yaml-3-1';

// detecting
await detect('openapi: 3.1.0'); // => true
await detect('test'); // => false

// parsing
const parseResult = await parse('openapi: 3.1.0', { sourceMap: true });

Indirect usage

You can omit the mediaType option here, but please read Word on detect vs mediaTypes before you do so.

import ApiDOMParser from '@swagger-api/apidom-parser';
import * as openApiYamlAdapter from '@swagger-api/apidom-parser-adapter-openapi-yaml-3-1';

const parser = new ApiDOMParser();

parser.use(openApiYamlAdapter);

const parseResult = await parser.parse('openapi: 3.1.0', { mediaType: openApiYamlAdapter.mediaTypes.latest('yaml') });

Changelog

1.0.0-alpha.10 (2024-10-21)

Bug Fixes

• apidom-parser-adapter-openapi-json-3-0: drop rc version support (#4320) (b8afa76), closes #2265
• playground: fix importing definition from URL (#4318) (3d32525)
• security: fix security issue in jsonpath-plus prod dependency (54c291f), closes #4380 #4386