npm package: @speclynx/apidom-ns-openapi-2
Description: OpenAPI 2.0 namespace for ApiDOM.
Author: Vladimir Gorej
Latest version: 4.3.1

# @speclynx/apidom-ns-openapi-2

`@speclynx/apidom-ns-openapi-2` contains ApiDOM namespace supports following OpenAPI specification versions:

- [OpenAPI 2.0 specification](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/2.0.md)

## Installation

You can install this package via [npm CLI](https://docs.npmjs.com/cli) by running the following command:

```sh
 $ npm install @speclynx/apidom-ns-openapi-2
```

## OpenAPI 2.0 namespace

OpenAPI 2.0 namespace consists of [number of elements](https://github.com/speclynx/apidom/tree/main/packages/apidom-ns-openapi-2/src/elements) implemented on top
of [primitive ones](https://github.com/speclynx/apidom/tree/main/packages/apidom-datamodel/src/primitives).

```js
import { Namespace } from '@speclynx/apidom-datamodel';
import openApi2Namespace from '@speclynx/apidom-ns-openapi-2';

const namespace = new Namespace();
namespace.use(openApi2Namespace);

const objectElement = new namespace.elements.Object();
const swaggerElement = new namespace.elements.Swagger();
```

When a namespace instance is created in this way, calling `use()` with the namespace plugin
will extend the base namespace with the OpenAPI 2.0 elements.

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

```js
import { SwaggerElement, InfoElement } from '@speclynx/apidom-ns-openapi-2';

const infoElement = new InfoElement();
const swaggerElement = new SwaggerElement();
```

## Predicates

This package exposes [predicates](https://github.com/speclynx/apidom/blob/main/packages/apidom-ns-openapi-2/src/predicates.ts)
for all higher order elements that are part of this namespace.

```js
import { isSwaggerElement, SwaggerElement } from '@speclynx/apidom-ns-openapi-2';

const swaggerElement = new SwaggerElement();

isSwaggerElement(swaggerElement); // => true
```

## Traversal

Traversing ApiDOM in this namespace is possible by using `traverse` function from `@speclynx/apidom-traverse` package.
`traverse` uses a Path-based visitor API where visitor methods receive a `Path` object,
and the actual element is accessed via `path.node`.

```js
import { traverse } from '@speclynx/apidom-traverse';
import { SwaggerElement } from '@speclynx/apidom-ns-openapi-2';

const element = new SwaggerElement();

const visitor = {
  SwaggerElement(path) {
    const swaggerElement = path.node;
    console.dir(swaggerElement);
  },
};

traverse(element, visitor);
```

## 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**:

```js
import { InfoElement } from '@speclynx/apidom-ns-openapi-2';

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

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

**Refracting generic ApiDOM structures**:

```js
import { ObjectElement } from '@speclynx/apidom-core';
import { InfoElement } from '@speclynx/apidom-ns-openapi-2';

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.
Plugin visitors use the Path-based API where visitor methods receive a `Path` object,
and the actual element is accessed via `path.node`.

```js
import { ObjectElement } from '@speclynx/apidom-core';
import { InfoElement } from '@speclynx/apidom-ns-openapi-2';

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) {
      const infoElement = path.node;
      infoElement.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.

```js
import { parse } from '@speclynx/apidom-parser-adapter-yaml-1-2';
import { refractorPluginReplaceEmptyElement, SwaggerElement } from '@speclynx/apidom-ns-openapi-2';

const yamlDefinition = `
swagger: 2.0
info:
`;
const apiDOM = await parse(yamlDefinition);
const swaggerElement = SwaggerElement.refract(apiDOM.result, {
  plugins: [refractorPluginReplaceEmptyElement()],
});

// =>
// (SwaggerElement
//   (MemberElement
//     (StringElement)
//     (SwaggerVersionElement))
//   (MemberElement
//     (StringElement)
//     (InfoElement)))

// => without the plugin the result would be as follows:
// (SwaggerElement
//   (MemberElement
//     (StringElement)
//     (SwaggerVersionElement))
//   (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.

```js
import { toValue } from '@speclynx/apidom-core';
import { parse } from '@speclynx/apidom-parser-adapter-yaml-1-2';
import { refractorPluginNormalizeParameters, SwaggerElement } from '@speclynx/apidom-ns-openapi-2';

const yamlDefinition = `
swagger: "2.0"
paths:
  /:
    parameters:
      - name: param1
        in: query
        type: string
      - name: param2
        in: query
        type: string
    get: {}
`;
const apiDOM = await parse(yamlDefinition);
const swaggerElement = SwaggerElement.refract(apiDOM.result, {
  plugins: [refractorPluginNormalizeParameters()],
});

toValue(swaggerElement);
// =>
// {
//   "swagger": "2.0",
//   "paths": {
//     "/": {
//       "parameters": [
//         {
//           "name": "param1",
//           "in": "query",
//           "type": "string"
//         },
//         {
//           "name": "param2",
//           "in": "query",
//           "type": "string"
//         }
//       ],
//       "get": {
//         "parameters": [
//           {
//             "name": "param1",
//             "in": "query",
//             "type": "string"
//           },
//           {
//             "name": "param2",
//             "in": "query",
//             "type": "string"
//           }
//         ]
//       }
//     }
//   }
// }
```

#### Normalize Security Requirements Objects plugin

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

```js
import { toValue } from '@speclynx/apidom-core';
import { parse } from '@speclynx/apidom-parser-adapter-yaml-1-2';
import { refractorPluginNormalizeSecurityRequirements, SwaggerElement } from '@speclynx/apidom-ns-openapi-2';

const yamlDefinition = `
swagger: "2.0"
security:
  - petstore_auth:
      - write:pets
      - read:pets
paths:
  /:
    get: {}
`;
const apiDOM = await parse(yamlDefinition);
const swaggerElement = SwaggerElement.refract(apiDOM.result, {
  plugins: [refractorPluginNormalizeSecurityRequirements()],
});

toValue(swaggerElement);
// =>
// {
//   "swagger": "2.0",
//   "security": [
//     {
//       "petstore_auth": [
//         "write:pets",
//         "read:pets"
//       ]
//     }
//   ],
//   "paths": {
//     "/": {
//       "get": {
//         "security": [
//           {
//             "petstore_auth": [
//               "write:pets",
//               "read:pets"
//             ]
//           }
//         ]
//       }
//     }
//   }
// }
```

## Implementation progress

Only fully implemented specification objects should be checked here.

- [x] [Swagger Object](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/2.0.md#user-content-swagger-object)
- [x] [Info Object](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/2.0.md#user-content-info-object)
- [x] [Contact Object](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/2.0.md#user-content-contact-object)
- [x] [License Object](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/2.0.md#user-content-license-object)
- [x] [Paths Object](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/2.0.md#user-content-paths-object)
- [x] [Path Item Object](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/2.0.md#user-content-path-item-object)
- [x] [Operation Object](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/2.0.md#user-content-operation-object)
- [x] [External Documentation Object](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/2.0.md#user-content-external-documentation-object)
- [x] [Parameter Object](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/2.0.md#user-content-parameter-object)
- [x] [Items Object](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/2.0.md#user-content-items-object)
- [x] [Responses Object](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/2.0.md#user-content-responses-object)
- [x] [Response Object](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/2.0.md#user-content-response-object)
- [x] [Headers Object](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/2.0.md#user-content-headers-object)
- [x] [Example Object](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/2.0.md#user-content-example-object)
- [x] [Header Object](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/2.0.md#user-content-header-object)
- [x] [Tag Object](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/2.0.md#user-content-tag-object)
- [x] [Reference Object](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/2.0.md#user-content-reference-object)
- [x] [JSON Reference Object](https://datatracker.ietf.org/doc/html/draft-pbryan-zyp-json-ref-02)
- [x] [Schema Object](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/2.0.md#user-content-schema-object)
- [x] [XML Object](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/2.0.md#user-content-xml-object)
- [x] [Definitions Object](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/2.0.md#user-content-definitions-object)
- [x] [Parameters Definitions Object](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/2.0.md#user-content-paramters-definitions-object)
- [x] [Responses Definitions Object](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/2.0.md#user-content-responses-definitions-object)
- [x] [Security Definitions Object](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/2.0.md#user-content-security-definitions-object)
- [x] [Security Scheme Object](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/2.0.md#user-content-security-scheme-object)
- [x] [Scopes Object](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/2.0.md#user-content-scopes-object)
- [x] [Security Requirement Object](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/2.0.md#user-content-security-requirement-object)
- [x] [Specification extensions](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/2.0.md#user-content-specification-extensions)