README.md

OpenApi31-TS

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

For OpenAPI 3.0.x contracts see instead: openapi3-ts.

How to use

This library provides an internal DSL and Typescript interfaces to help to build and produce OpenAPI Specfications and to format them as JSON and YAML.

See the test in the *.spec.ts files to see how to use it.

Main differences between OpenAPI 3.0 and OpenAPI 3.1

For working with OpenAPI v. 3.1.0 use this library, for OpenAPI 3.0.0 use this other twin one: openapi3-ts.

Main differences in implementation are:

1. Semantic version is dropped.
2. Different JSON Schema rules applies (this library is not providing support for JSON Schema validation).
   • OpenAPI 3.0.0 uses JSON Schema Specification Wright Draft 00
   • OpenAPI 3.1.0 uses JSON Schema Specification Draft 2020-12
3. Derived from the JSON Schema version change:
   • exclusiveMaximum was a boolean on OpenAPI 3.0, now is a number in OpenAPI 3.1.
   • exclusiveMinimum was a boolean on OpenAPI 3.0, now is a number in OpenAPI 3.1.
4. Added support for Webhooks on OpenAPI 3.1.0
5. Single example is deprecated in favour of examples.
6. Type can now be an array.
7. Type can be null with: nullable: true.
8. Paths are optional.

Read for a more detailed comparison.

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 openapi31-ts

Versions and Changelog

See changelog.

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-2023. Pedro J. Molina at Metadev S.L. https://metadev.pro & contributors.