117 lines
5.2 KiB
Markdown
117 lines
5.2 KiB
Markdown
# OpenAPI Specification Schemas
|
||
|
||
[](https://github.com/APIDevTools/openapi-schemas/actions)
|
||
[](https://github.com/APIDevTools/openapi-schemas/actions)
|
||
|
||
[](https://coveralls.io/github/APIDevTools/openapi-schemas)
|
||
[](https://david-dm.org/APIDevTools/openapi-schemas)
|
||
|
||
[](https://www.npmjs.com/package/@apidevtools/openapi-schemas)
|
||
[](LICENSE)
|
||
[](https://plant.treeware.earth/APIDevTools/openapi-schemas)
|
||
|
||
|
||
|
||
This package contains [**the official JSON Schemas**](https://github.com/OAI/OpenAPI-Specification/tree/master/schemas) for every version of Swagger/OpenAPI Specification:
|
||
|
||
| Version | Schema | Docs
|
||
|---------|--------|-------
|
||
| Swagger 1.2 | [v1.2 schema](https://github.com/OAI/OpenAPI-Specification/tree/master/schemas/v1.2) | [v1.2 docs](https://github.com/OAI/OpenAPI-Specification/blob/master/versions/1.2.md)
|
||
| Swagger 2.0 | [v2.0 schema](https://github.com/OAI/OpenAPI-Specification/blob/master/schemas/v2.0/schema.json) | [v2.0 docs](https://github.com/OAI/OpenAPI-Specification/blob/master/versions/2.0.md)
|
||
| OpenAPI 3.0.x | [v3.0.x schema](https://github.com/OAI/OpenAPI-Specification/blob/master/schemas/v3.0/schema.json) | [v3.0.3 docs](https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.3.md)
|
||
| OpenAPI 3.1.x | [v3.1.x schema](https://github.com/OAI/OpenAPI-Specification/blob/master/schemas/v3.1/schema.json) | [v3.1.0 docs](https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.1.0.md)
|
||
|
||
|
||
All schemas are kept up-to-date with the latest official definitions via an automated CI/CD job. 🤖📦
|
||
|
||
|
||
|
||
Installation
|
||
--------------------------
|
||
You can install OpenAPI Schemas via [npm](https://docs.npmjs.com/about-npm/).
|
||
|
||
```bash
|
||
npm install @apidevtools/openapi-schemas
|
||
```
|
||
|
||
|
||
|
||
Usage
|
||
--------------------------
|
||
|
||
The default export contains all OpenAPI Specification versions:
|
||
|
||
```javascript
|
||
const openapi = require("@apidevtools/openapi-schemas");
|
||
|
||
console.log(openapi.v1); // { $schema, id, properties, definitions, ... }
|
||
console.log(openapi.v2); // { $schema, id, properties, definitions, ... }
|
||
console.log(openapi.v3); // { $schema, id, properties, definitions, ... }
|
||
console.log(openapi.v31); // { $schema, id, properties, definitions, ... }
|
||
```
|
||
|
||
Or you can import the specific version(s) that you need:
|
||
|
||
```javascript
|
||
const { openapiV1, openapiV2, openapiV3, openapiV31 } = require("@apidevtools/openapi-schemas");
|
||
|
||
console.log(openapiV1); // { $schema, id, properties, definitions, ... }
|
||
console.log(openapiV2); // { $schema, id, properties, definitions, ... }
|
||
console.log(openapiV3); // { $schema, id, properties, definitions, ... }
|
||
console.log(openapiV31); // { $schema, id, properties, definitions, ... }
|
||
```
|
||
|
||
You can use a JSON Schema validator such as [Z-Schema](https://www.npmjs.com/package/z-schema) or [AJV](https://www.npmjs.com/package/ajv) to validate OpenAPI definitions against the specification.
|
||
|
||
```javascript
|
||
const { openapiV31 } = require("@apidevtools/openapi-schemas");
|
||
const ZSchema = require("z-schema");
|
||
|
||
// Create a ZSchema validator
|
||
let validator = new ZSchema();
|
||
|
||
// Validate an OpenAPI definition against the OpenAPI v3.0 specification
|
||
validator.validate(openapiDefinition, openapiV31);
|
||
```
|
||
|
||
|
||
|
||
Contributing
|
||
--------------------------
|
||
Contributions, enhancements, and bug-fixes are welcome! [Open an issue](https://github.com/APIDevTools/openapi-schemas/issues) on GitHub and [submit a pull request](https://github.com/APIDevTools/openapi-schemas/pulls).
|
||
|
||
#### Building
|
||
To build the project locally on your computer:
|
||
|
||
1. __Clone this repo__<br>
|
||
`git clone https://github.com/APIDevTools/openapi-schemas.git`
|
||
|
||
2. __Install dependencies__<br>
|
||
`npm install`
|
||
|
||
3. __Build the code__<br>
|
||
`npm run build`
|
||
|
||
4. __Run the tests__<br>
|
||
`npm test`
|
||
|
||
|
||
|
||
License
|
||
--------------------------
|
||
OpenAPI Schemas is 100% free and open-source, under the [MIT license](LICENSE). Use it however you want.
|
||
|
||
This package is [Treeware](http://treeware.earth). If you use it in production, then we ask that you [**buy the world a tree**](https://plant.treeware.earth/APIDevTools/openapi-schemas) to thank us for our work. By contributing to the Treeware forest you’ll be creating employment for local families and restoring wildlife habitats.
|
||
|
||
|
||
|
||
Big Thanks To
|
||
--------------------------
|
||
Thanks to these awesome companies for their support of Open Source developers ❤
|
||
|
||
[](https://github.com/open-source)
|
||
[](https://www.npmjs.com/)
|
||
[](https://coveralls.io)
|
||
[](https://travis-ci.com)
|
||
[](https://saucelabs.com)
|