@swagger-api/apidom-ns-openapi-3-1
Advanced tools
Parser adapter for parsing JSON documents into AsyncAPI 2.x.y namespace.
@swagger-api/apidom-ns-openapi-3-1 is an npm package designed to work with the OpenAPI 3.1 specification. It provides tools for parsing, validating, and manipulating OpenAPI documents, making it easier for developers to work with API definitions.
Parsing OpenAPI Documents
This feature allows you to parse an OpenAPI 3.1 document from a string format into a JavaScript object. This is useful for programmatically accessing and manipulating the contents of an OpenAPI document.
const { parse } = require('@swagger-api/apidom-ns-openapi-3-1');
const openApiDoc = `
openapi: 3.1.0
info:
title: Sample API
version: 1.0.0
paths:
/pets:
get:
summary: List all pets
responses:
'200':
description: A list of pets.
`;
const parsedDoc = parse(openApiDoc);
console.log(parsedDoc);Validating OpenAPI Documents
This feature allows you to validate an OpenAPI 3.1 document to ensure it adheres to the specification. This is useful for catching errors and ensuring the document is correctly formatted.
const { validate } = require('@swagger-api/apidom-ns-openapi-3-1');
const openApiDoc = `
openapi: 3.1.0
info:
title: Sample API
version: 1.0.0
paths:
/pets:
get:
summary: List all pets
responses:
'200':
description: A list of pets.
`;
const validationResult = validate(openApiDoc);
console.log(validationResult);Manipulating OpenAPI Documents
This feature allows you to manipulate an OpenAPI 3.1 document by parsing it into a JavaScript object, making changes, and then serializing it back into a string format. This is useful for programmatically updating API definitions.
const { parse, serialize } = require('@swagger-api/apidom-ns-openapi-3-1');
const openApiDoc = `
openapi: 3.1.0
info:
title: Sample API
version: 1.0.0
paths:
/pets:
get:
summary: List all pets
responses:
'200':
description: A list of pets.
`;
let parsedDoc = parse(openApiDoc);
parsedDoc.info.title = 'Updated API Title';
const updatedDoc = serialize(parsedDoc);
console.log(updatedDoc);swagger-parser is a powerful npm package for parsing, validating, and dereferencing Swagger and OpenAPI documents. It supports both OpenAPI 2.0 and 3.0, but does not yet support OpenAPI 3.1. It is known for its robust validation and dereferencing capabilities.
openapi-types is a TypeScript library that provides type definitions for OpenAPI 3.0 and 3.1. It is useful for developers who want to ensure type safety when working with OpenAPI documents in TypeScript. Unlike @swagger-api/apidom-ns-openapi-3-1, it does not provide parsing or validation functionalities.
swagger-client is an npm package that allows you to interact with Swagger and OpenAPI documents. It provides tools for making HTTP requests to APIs defined by OpenAPI documents and for parsing and validating these documents. It supports OpenAPI 2.0 and 3.0, but not 3.1.
@swagger-api/apidom-ns-openapi-3-1 contains ApiDOM namespace specific to OpenApi 3.1.0 specification.
You can install this package via npm CLI by running the following command:
$ npm install @swagger-api/apidom-ns-openapi-3-1
OpenApi 3.1.0 namespace consists of number of elements implemented on top of primitive ones.
import { createNamespace } from '@swagger-api/apidom-core';
import openApi3_1Namespace from '@swagger-api/apidom-ns-openapi-3-1';
const namespace = createNamespace(openApi3_1Namespace);
const objectElement = new namespace.elements.Object();
const openApiElement = new namespace.elements.OpenApi3_1();
When namespace instance is created in this way, it will extend the base namespace with the namespace provided as an argument.
Elements from the namespace can also be used directly by importing them.
import { OpenApi3_1Element, InfoElement } from '@swagger-api/apidom-ns-openapi-3-1';
const infoElement = new InfoElement();
const openApiElement = new OpenApi3_1Element();
This package exposes predicates for all higher order elements that are part of this namespace.
import { isOpenApi3_1Element, OpenApi3_1Element } from '@swagger-api/apidom-ns-openapi-3-1';
const openApiElement = new OpenApi3_1Element();
isOpenApi3_1Element(openApiElement); // => true
Traversing ApiDOM in this namespace is possible by using visit function from apidom package.
This package comes with its own keyMap and nodeTypeGetter.
To learn more about these visit configuration options please refer to @swagger-api/apidom-ast documentation.
import { visit } from '@swagger-api/apidom-core';
import { OpenApi3_1Element, keyMap, getNodeType } from '@swagger-api/apidom-ns-openapi-3-1';
const element = new OpenApi3_1Element();
const visitor = {
OpenApi3_1Element(openApiElement) {
console.dir(openApiElement);
},
};
visit(element, visitor, { keyMap, nodeTypeGetter: getNodeType });
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 '@swagger-api/apidom-ns-openapi-3-1';
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 '@swagger-api/apidom-core';
import { InfoElement } from '@swagger-api/apidom-ns-openapi-3-1';
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' })
Refractors can accept plugins as a second argument of refract static method.
import { ObjectElement } from '@swagger-api/apidom-core';
import { InfoElement } from '@swagger-api/apidom-ns-openapi-3-1';
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(infoElement) {
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).
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 '@swagger-api/apidom-parser-adapter-yaml-1-2';
import { refractorPluginReplaceEmptyElement, OpenApi3_1Element } from '@swagger-api/apidom-ns-openapi-3-1';
const yamlDefinition = `
openapi: 3.1.0
info:
`;
const apiDOM = await parse(yamlDefinition);
const openApiElement = OpenApi3_1Element.refract(apiDOM.result, {
plugins: [refractorPluginReplaceEmptyElement()],
});
// =>
// (OpenApi3_1Element
// (MemberElement
// (StringElement)
// (OpenapiElement))
// (MemberElement
// (StringElement)
// (InfoElement)))
// => without the plugin the result would be as follows:
// (OpenApi3_1Element
// (MemberElement
// (StringElement)
// (OpenapiElement))
// (MemberElement
// (StringElement)
// (StringElement)))
Existing Operation.operationId fields are normalized into snake case form.
Operation Objects, that do not define operationId field, are left untouched.
Original operationId is stored in meta and as new __originalOperationId field.
This plugin also guarantees the uniqueness of all defined Operation.operationId fields,
and make sure Link.operationId fields are pointing to correct and normalized Operation.operationId fields.
import { toValue } from '@swagger-api/apidom-core';
import { parse } from '@swagger-api/apidom-parser-adapter-yaml-1-2';
import { refractorPluginNormalizeOperationIds, OpenApi3_1Element } from '@swagger-api/apidom-ns-openapi-3-1';
const yamlDefinition = `
openapi: 3.1.0
paths:
/:
get:
operationId: get operation ^
`;
const apiDOM = await parse(yamlDefinition);
const openApiElement = OpenApi3_1Element.refract(apiDOM.result, {
plugins: [refractorPluginNormalizeOperationIds()],
});
toValue(openApiElement);
// =>
// {
// "openapi": "3.1.0",
// "paths": {
// "/": {
// "get": {
// "operationId": "getoperation_"
// }
// }
// }
// }
This plugin also accepts custom normalization function that will determine how normalized Operation.operationId fields should look like.
import { toValue } from '@swagger-api/apidom-core';
import { parse } from '@swagger-api/apidom-parser-adapter-yaml-1-2';
import { refractorPluginNormalizeOperationIds, OpenApi3_1Element } from '@swagger-api/apidom-ns-openapi-3-1';
const yamlDefinition = `
openapi: 3.1.0
paths:
/:
get:
operationId: get operation ^
`;
const apiDOM = await parse(yamlDefinition);
const openApiElement = OpenApi3_1Element.refract(apiDOM.result, {
plugins: [refractorPluginNormalizeOperationIds({
operationIdNormalizer: (operationId: string, path: string, method: string): string => {
// operationId - value of Original.operationId field
// path - field pattern of Paths Object under which Path Item containing this Operation is registered
// method - name of HTTP method under which the Operation is registered in Path Item
},
})],
});
toValue(openApiElement);
// =>
// {
// "openapi": "3.1.0",
// "paths": {
// "/": {
// "get": {
// "operationId": "<normalized-operation-id>"
// }
// }
// }
// }
Duplicates Parameters from Path Items to Operation Objects using following rules:
import { toValue } from '@swagger-api/apidom-core';
import { parse } from '@swagger-api/apidom-parser-adapter-yaml-1-2';
import { refractorPluginNormalizeParameters, OpenApi3_1Element } from '@swagger-api/apidom-ns-openapi-3-1';
const yamlDefinition = `
openapi: 3.1.0
paths:
/:
parameters:
- name: param1
in: query
- name: param2
in: query
get: {}
`;
const apiDOM = await parse(yamlDefinition);
const openApiElement = OpenApi3_1Element.refract(apiDOM.result, {
plugins: [refractorPluginNormalizeParameters()],
});
toValue(openApiElement);
// =>
// {
// "openapi": "3.1.0",
// "paths": {
// "/": {
// "parameters": [
// {
// "name": "param1",
// "in": "query"
// },
// {
// "name": "param2",
// "in": "query"
// }
// ],
// "get": {
// "parameters": [
// {
// "name": "param1",
// "in": "query"
// },
// {
// "name": "param2",
// "in": "query"
// }
// ],
// }
// }
// }
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 '@swagger-api/apidom-core';
import { parse } from '@swagger-api/apidom-parser-adapter-yaml-1-2';
import { refractorPluginNormalizeSecurityRequirements, OpenApi3_1Element } from '@swagger-api/apidom-ns-openapi-3-1';
const yamlDefinition = `
openapi: 3.1.0
security:
- petstore_auth:
- write:pets
- read:pets
paths:
/:
get: {}
`;
const apiDOM = await parse(yamlDefinition);
const openApiElement = OpenApi3_1Element.refract(apiDOM.result, {
plugins: [refractorPluginNormalizeSecurityRequirements()],
});
toValue(openApiElement);
// =>
// {
// "openapi": "3.1.0",
// "security": [
// {
// "petstore_auth": [
// "write:pets",
// "read:pets"
// ]
// }
// ],
// "paths": {
// "/": {
// "get": {
// "security": [
// {
// "petstore_auth": [
// "write:pets",
// "read:pets"
// ]
// }
// ]
// }
// }
// }
// }
List of Server Objects can be defined in OpenAPI 3.1 on multiple levels:
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 '@swagger-api/apidom-core';
import { parse } from '@swagger-api/apidom-parser-adapter-yaml-1-2';
import { refractorPluginNormalizeServers, OpenApi3_1Element } from '@swagger-api/apidom-ns-openapi-3-1';
const yamlDefinition = `
openapi: 3.1.0
servers:
- url: https://example.com/
description: production server
paths:
/:
get: {}
`;
const apiDOM = await parse(yamlDefinition);
const openApiElement = OpenApi3_1Element.refract(apiDOM.result, {
plugins: [refractorPluginNormalizeServers()],
});
toValue(openApiElement);
// =>
// {
// "openapi": "3.1.0",
// "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"
// }
// ]
// }
// }
// }
// }
Only fully implemented specification objects should be checked here.
FAQs
OpenAPI 3.1.x namespace for ApiDOM.
We found that @swagger-api/apidom-ns-openapi-3-1 demonstrated a healthy version release cadence and project activity because the last version was released less than a year ago. It has 1 open source maintainer collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Research
Security News
Socket is tracking a new trend where malicious actors are now exploiting the popularity of LLM research to spread malware through seemingly useful open source packages.
Security News
Research
Noxia, a new dark web bulletproof host, offers dirt cheap servers for Python, Node.js, Go, and Rust, enabling cybercriminals to distribute malware and execute supply chain attacks.
Company News
Socket safeguards companies from software supply chain attacks by detecting and preventing threats in open source code and empowering developers to secure their applications and critical services against malware and other security risks.