openapi3-ts

What is openapi3-ts?

The openapi3-ts npm package is a TypeScript library that provides types and utility functions for working with OpenAPI 3.0.x documents. It allows developers to create, manipulate, and validate OpenAPI specifications programmatically.

What are openapi3-ts's main functionalities?

Creating OpenAPI documents

This feature allows developers to create new OpenAPI documents by defining the necessary OpenAPI object structure in TypeScript. The code sample represents a basic OpenAPI document structure with the required fields.

{"openApi": "3.0.0","info": {"title": "Sample API","version": "1.0.0"},"paths": {}}

Manipulating OpenAPI documents

This feature allows developers to add or modify paths, operations, and other components within an OpenAPI document. The code sample demonstrates adding a new path with a GET operation to an existing OpenAPI document.

{"openApi": "3.0.0","info": {"title": "Sample API","version": "1.0.0"},"paths": {"/pets": {"get": {"summary": "List all pets","operationId": "listPets","tags": ["pets"],"responses": {"200": {"description": "An paged array of pets"}}}}}}

Validating OpenAPI documents

This feature provides the ability to validate OpenAPI documents against the OpenAPI 3.0.x specification. The code sample shows how to create a validator instance and validate an OpenAPI document.

const OpenAPIValidator = require('openapi3-ts').OpenAPIValidator;const openApiDoc = {openApi: '3.0.0',info: {title: 'Sample API',version: '1.0.0'},paths: {}};const validator = new OpenAPIValidator(openApiDoc);const isValid = validator.validate();

Other packages similar to openapi3-ts

swagger-jsdoc

This package allows you to integrate Swagger using JSDoc comments directly in your code. Unlike openapi3-ts, which is more about manipulating OpenAPI objects, swagger-jsdoc is focused on generating OpenAPI documentation from inline comments.

swagger-ui-express

This package is used to serve auto-generated swagger-ui generated API docs from express, based on a swagger.json file. It is different from openapi3-ts in that it is more about serving and displaying documentation rather than creating or manipulating OpenAPI objects.

openapi-validator

This package is an OpenAPI validator that validates API requests and responses against an OpenAPI document. It is similar to the validation functionality of openapi3-ts but is a standalone package dedicated to validation.

README

OpenApi3-TS

TypeScript library to help building OpenAPI 3.x compliant API contracts.

Version 4

Breaking change notice:

Version 4.0 Adds explicit support for OAS 3.0 and OAS 3.1 as separate implementations.

To use version 3.1 import

import { oas31 } from 'openapi3-ts';

Or directly import from subpath:

import { OpenAPIObject, OpenApiBuilder } from 'openapi3-ts/oas31';

To use version 3.0 import

import { oas30 } from 'openapi3-ts';

Or directly import from subpath:

import { OpenAPIObject, OpenApiBuilder } from 'openapi3-ts/oas30';

Includes

• /src/model TS typed interfaces for helping building a contract.
• /src/dsl Fluent DSL for building a contract.

Install

Install package via npm:

npm i --save openapi3-ts

Documentation, Versions, and Changelog

• Documentation.
• See changelog for version and changes.

References

• OpenAPI spec 3.1.0. https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.1.0.md

License

Licensed under the MIT License.

Credits

Contact: Pedro J. Molina | github: pjmolina | twitter: pmolinam

(c) 2017-2024. Pedro J. Molina at Metadev S.L. https://metadev.pro & contributors.