@speclynx/apidom-ns-openapi-3-0

@speclynx/apidom-ns-openapi-3-0 contains ApiDOM namespace specific to OpenAPI 3.0.x specification, supporting the following versions:

Installation

You can install this package via npm CLI by running the following command:

 $ npm install @speclynx/apidom-ns-openapi-3-0

OpenAPI 3.0.x namespace

OpenAPI 3.0.x namespace consists of number of elements implemented on top of primitive ones.

Elements from the namespace can be used directly by importing them.

import { OpenApi3_0Element, InfoElement } from '@speclynx/apidom-ns-openapi-3-0';

const infoElement = new InfoElement();
const openApiElement = new OpenApi3_0Element();

Predicates

This package exposes predicates for all higher order elements that are part of this namespace.

import { isOpenApi3_0Element, OpenApi3_0Element } from '@speclynx/apidom-ns-openapi-3-0';

const openApiElement = new OpenApi3_0Element();

isOpenApi3_0Element(openApiElement); // => true

Traversal

Traversing ApiDOM in this namespace is possible by using traverse function from @speclynx/apidom-traverse package. Visitor methods receive a Path object that provides access to the current node and traversal control.

import { traverse } from '@speclynx/apidom-traverse';
import { OpenApi3_0Element } from '@speclynx/apidom-ns-openapi-3-0';

const element = new OpenApi3_0Element();

const visitor = {
  OpenApi3_0Element(path) {
    const openApiElement = path.node;
    console.dir(openApiElement);
    path.stop(); // stop traversal
  },
};

traverse(element, visitor);

The Path object provides several useful methods:

path.node - the current element being visited
path.stop() - stop traversal completely
path.skip() - skip visiting children of the current node
path.remove() - remove the current node from its parent
path.replaceWith(newNode) - replace the current node with a new node
path.getAncestorNodes() - get all ancestor nodes (parent to root order)

Refractors

Refractor is a special layer inside the namespace that can transform either JavaScript structures or generic ApiDOM structures into structures built from elements of this namespace.

Refracting JavaScript structures:

import { InfoElement } from '@speclynx/apidom-ns-openapi-3-0';

const object = {
    title: 'my title',
    description: 'my description',
    version: '0.1.0',
};

InfoElement.refract(object); // => InfoElement({ title, description, version })

Refracting generic ApiDOM structures:

import { ObjectElement } from '@speclynx/apidom-datamodel';
import { InfoElement } from '@speclynx/apidom-ns-openapi-3-0';

const objectElement = new ObjectElement({
    title: 'my title',
    description: 'my description',
    version: '0.1.0',
});

InfoElement.refract(objectElement); // => InfoElement({ title = 'my title', description = 'my description', version = '0.1.0' })

Refractor plugins

Refractors can accept plugins as a second argument of refract static method.

import { ObjectElement } from '@speclynx/apidom-datamodel';
import { InfoElement } from '@speclynx/apidom-ns-openapi-3-0';

const objectElement = new ObjectElement({
    title: 'my title',
    description: 'my description',
    version: '0.1.0',
});

const plugin = ({ predicates, namespace }) => ({
  name: 'plugin',
  pre() {
      console.dir('runs before traversal');
  },
  visitor: {
    InfoElement(path) {
      path.node.version = '2.0.0';
    },
  },
  post() {
      console.dir('runs after traversal');
  },
});

InfoElement.refract(objectElement, { plugins: [plugin] }); // => InfoElement({ title = 'my title', description = 'my description', version = '2.0.0' })

You can define as many plugins as needed to enhance the resulting namespaced ApiDOM structure. If multiple plugins with the same visitor method are defined, they run in parallel (just like in Babel).

Replace Empty Element plugin

This plugin is specific to YAML 1.2 format, which allows defining key-value pairs with empty key, empty value, or both. If the value is not provided in YAML format, this plugin compensates for this missing value with the most appropriate semantic element type.

import { parse } from '@speclynx/apidom-parser-adapter-yaml-1-2';
import { refractorPluginReplaceEmptyElement, OpenApi3_0Element } from '@speclynx/apidom-ns-openapi-3-0';

const yamlDefinition = `
openapi: 3.0.4
info:
`;
const apiDOM = await parse(yamlDefinition);
const openApiElement = OpenApi3_0Element.refract(apiDOM.result, {
  plugins: [refractorPluginReplaceEmptyElement()],
});

// =>
// (OpenApi3_0Element
//   (MemberElement
//     (StringElement)
//     (OpenapiElement))
//   (MemberElement
//     (StringElement)
//     (InfoElement)))

// => without the plugin the result would be as follows:
// (OpenApi3_0Element
//   (MemberElement
//     (StringElement)
//     (OpenapiElement))
//   (MemberElement
//     (StringElement)
//     (StringElement)))

Normalize Parameter Objects plugin

Duplicates Parameters from Path Items to Operation Objects using following rules:

An Operation-level parameter with the same name and location overrides the inherited Path Item parameter, but Path Item parameters can never be removed at the Operation level
The list MUST NOT include duplicated parameters
A unique parameter is defined by a combination of a name and location.

import { toValue } from '@speclynx/apidom-core';
import { parse } from '@speclynx/apidom-parser-adapter-yaml-1-2';
import { refractorPluginNormalizeParameters, OpenApi3_0Element } from '@speclynx/apidom-ns-openapi-3-0';

const yamlDefinition = `
openapi: 3.0.4
paths:
  /:
    parameters:
      - name: param1
        in: query
      - name: param2
        in: query
    get: {}
`;
const apiDOM = await parse(yamlDefinition);
const openApiElement = OpenApi3_0Element.refract(apiDOM.result, {
  plugins: [refractorPluginNormalizeParameters()],
});

toValue(openApiElement);
// =>
// {
//   "openapi": "3.0.4",
//   "paths": {
//     "/": {
//       "parameters": [
//         {
//           "name": "param1",
//           "in": "query"
//         },
//         {
//           "name": "param2",
//           "in": "query"
//         }
//       ],
//       "get": {
//         "parameters": [
//           {
//             "name": "param1",
//             "in": "query"
//           },
//           {
//             "name": "param2",
//             "in": "query"
//           }
//         ]
//       }
//     }
//   }
// }

Normalize Security Requirements Objects plugin

Operation.security definition overrides any declared top-level security from OpenAPI.security field. If Operation.security field is not defined, this field will inherit security from OpenAPI.security field.

import { toValue } from '@speclynx/apidom-core';
import { parse } from '@speclynx/apidom-parser-adapter-yaml-1-2';
import { refractorPluginNormalizeSecurityRequirements, OpenApi3_0Element } from '@speclynx/apidom-ns-openapi-3-0';

const yamlDefinition = `
openapi: 3.0.4
security:
  - petstore_auth:
      - write:pets
      - read:pets
paths:
  /:
    get: {}
`;
const apiDOM = await parse(yamlDefinition);
const openApiElement = OpenApi3_0Element.refract(apiDOM.result, {
  plugins: [refractorPluginNormalizeSecurityRequirements()],
});

toValue(openApiElement);
// =>
// {
//   "openapi": "3.0.4",
//   "security": [
//     {
//       "petstore_auth": [
//         "write:pets",
//         "read:pets"
//       ]
//     }
//   ],
//   "paths": {
//     "/": {
//       "get": {
//         "security": [
//           {
//             "petstore_auth": [
//               "write:pets",
//               "read:pets"
//             ]
//           }
//         ]
//       }
//     }
//   }
// }

Normalize Server Objects plugin

List of Server Objects can be defined in OpenAPI 3.0 on multiple levels:

OpenAPI.servers
PathItem.servers
Operation.servers

If an alternative server object is specified at the Path Item Object level, it will override OpenAPI.servers. If an alternative server object is specified at the Operation Object level, it will override PathItem.servers and OpenAPI.servers respectively.

import { toValue } from '@speclynx/apidom-core';
import { parse } from '@speclynx/apidom-parser-adapter-yaml-1-2';
import { refractorPluginNormalizeServers, OpenApi3_0Element } from '@speclynx/apidom-ns-openapi-3-0';

const yamlDefinition = `
openapi: 3.0.4
servers:
 - url: https://example.com/
   description: production server
paths:
  /:
    get: {}
`;
const apiDOM = await parse(yamlDefinition);
const openApiElement = OpenApi3_0Element.refract(apiDOM.result, {
  plugins: [refractorPluginNormalizeServers()],
});

toValue(openApiElement);
// =>
// {
//   "openapi": "3.0.4",
//   "servers": [
//     {
//       "url": "https://example.com/",
//       "description": "production server"
//     }
//   ],
//   "paths": {
//     "/": {
//       "servers": [
//         {
//           "url": "https://example.com/",
//           "description": "production server"
//         }
//       ],
//       "get": {
//         "servers": [
//           {
//             "url": "https://example.com/",
//             "description": "production server"
//           }
//         ]
//       }
//     }
//   }
// }

Implementation progress

Only fully implemented specification objects should be checked here.