Skip to content

Commit

Permalink
Adding openapi-schema-validator and allowing for schema extentions in…
Browse files Browse the repository at this point in the history
… express-openapi (#71)
  • Loading branch information
jsdevel committed Jun 23, 2018
1 parent 3dcb0e6 commit f13f11c
Show file tree
Hide file tree
Showing 25 changed files with 2,749 additions and 19 deletions.
2 changes: 1 addition & 1 deletion README.md
Original file line number Diff line number Diff line change
Expand Up @@ -17,7 +17,7 @@
* [openapi-jsonschema-parameters](https://github.com/kogosoftwarellc/open-api/tree/master/packages/openapi-jsonschema-parameters)
* [openapi-request-coercer](https://github.com/kogosoftwarellc/open-api/tree/master/packages/openapi-request-coercer)
* [openapi-response-validator](https://github.com/kogosoftwarellc/open-api/tree/master/packages/openapi-response-validator)
* [openapi-schema-validation](https://github.com/kogosoftwarellc/open-api/tree/master/packages/openapi-schema-validation)
* [openapi-schema-validator](https://github.com/kogosoftwarellc/open-api/tree/master/packages/openapi-schema-validator)

## LICENSE

Expand Down
29 changes: 28 additions & 1 deletion packages/express-openapi/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -26,7 +26,9 @@ and validation.
* Leverages security definitions for security management.
* See [express-openapi-security](https://github.com/kogosoftwarellc/open-api/tree/master/packages/express-openapi-security)
* Validates api documents.
* See [openapi-schema-validation](https://github.com/kogosoftwarellc/open-api/tree/master/packages/openapi-schema-validation)
* See [openapi-schema-validator](https://github.com/kogosoftwarellc/open-api/tree/master/packages/openapi-schema-validator)
* Supports schema extension.
* See [Extending OpenAPI Schema](#extending-openapi-schema)
* Configurable Middleware.
* See [Configuring Middleware](#configuring-middleware)
* Supports custom `format` validators.
Expand Down Expand Up @@ -306,6 +308,31 @@ OpenAPI allows vendor extensions to be used throughout your api doc.
Calling this operation with `paramname=5` will not affect the validity of the request
and your path handler will receive `paramName=5`.

### Extending OpenAPI Schema

* `x-express-openapi-schema-extension: {}` - Use this to extend the schema being used. An
example use case can be allowing `oneOf` with version 2.0 documents.

i.e.

```
x-express-openapi-schema-extension: {
definitions: {
schema: {
properties: {
oneOf: {
type: "array",
minItems: 1,
items: {
$ref: "#/definitions/schema"
}
}
}
}
}
}
```

### Configuring Middleware

You can directly control what middleware `express-openapi` adds to your express app
Expand Down
11 changes: 8 additions & 3 deletions packages/express-openapi/index.js
Original file line number Diff line number Diff line change
@@ -1,4 +1,5 @@
var ADDITIONAL_MIDDLEWARE_PROPERTY = 'x-express-openapi-additional-middleware';
var SCHEMA_EXTENSION_PROPERTY = 'x-express-openapi-schema-extension';
var OpenapiDefaultSetter = require('openapi-default-setter');
var OpenapiRequestCoercer = require('openapi-request-coercer');
var OpenapiResponseValidator = require('openapi-response-validator');
Expand All @@ -14,7 +15,7 @@ var PARAMETER_REF_REGEX = /^#\/parameters\/(.+)$/;
var RESPONSE_REF_REGEX = /^#\/(definitions|responses)\/(.+)$/;
var jsYaml = require('js-yaml');
var difunc = require('difunc');
var validateSchema = require('openapi-schema-validation').validate;
var OpenapiSchemaValidator = require('openapi-schema-validator');
var normalizeQueryParamsMiddleware = require('express-normalize-query-params-middleware');
var METHOD_ALIASES = {
// HTTP style
Expand Down Expand Up @@ -72,9 +73,13 @@ function initialize(args) {
var originalApiDoc = handleYaml(args.apiDoc);
// Make a copy of the apiDoc that we can safely modify.
var apiDoc = copy(originalApiDoc);
var validator = new OpenapiSchemaValidator({
version: apiDoc.openapi || apiDoc.swagger,
extensions: apiDoc[SCHEMA_EXTENSION_PROPERTY]
});

if (validateApiDoc) {
var apiDocValidation = validateSchema(apiDoc);
var apiDocValidation = validator.validate(apiDoc);

if (apiDocValidation.errors.length) {
console.error(loggingKey, 'Validating schema before populating paths');
Expand Down Expand Up @@ -332,7 +337,7 @@ function initialize(args) {
sortApiDocTags(apiDoc);

if (validateApiDoc) {
var apiDocValidation = validateSchema(apiDoc);
var apiDocValidation = validator.validate(apiDoc);

if (apiDocValidation.errors.length) {
console.error(loggingKey, 'Validating schema after populating paths');
Expand Down
23 changes: 11 additions & 12 deletions packages/express-openapi/package-lock.json

Some generated files are not rendered by default. Learn more about how customized files appear on GitHub.

4 changes: 2 additions & 2 deletions packages/express-openapi/package.json
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
{
"name": "express-openapi",
"version": "1.6.5",
"version": "1.7.0",
"description": "An unopinionated OpenAPI framework for express",
"scripts": {
"cover": "istanbul cover _mocha -- ./test/*.js",
Expand Down Expand Up @@ -31,7 +31,7 @@
"openapi-default-setter": "1.0.0",
"openapi-request-coercer": "1.0.0",
"openapi-response-validator": "1.0.0",
"openapi-schema-validation": "0.4.1",
"openapi-schema-validator": "1.0.0",
"openapi-security-handler": "1.0.0"
}
}
Original file line number Diff line number Diff line change
@@ -0,0 +1,204 @@
{
"host": "test-host",
"basePath": "/v3",
"definitions": {
"Error": {
"additionalProperties": true
},
"User": {
"properties": {
"name": {
"oneOf": [
{ "type": "string" },
{ "type": "null" }
]
},
"friends": {
"type": "array",
"items": {
"$ref": "#/definitions/User"
}
}

},
"required": [
"name"
]
}
},
"info": {
"title": "express-openapi sample project",
"version": "3.0.0"
},
"paths": {
"/apiDocs": {
"get": {
"description": "Returns the requested apiDoc",
"operationId": "getApiDoc",
"parameters": [
{
"description": "The type of apiDoc to return.",
"enum": [
"apiDoc",
"operationDoc"
],
"in": "query",
"name": "type",
"type": "string"
}
],
"responses": {
"200": {
"description": "The requested apiDoc.",
"schema": {
"type": "object"
}
},
"default": {
"description": "The requested apiDoc."
}
}
},
"parameters": []
},
"/users": {
"parameters": [],
"delete": {
"description": "Delete users.",
"operationId": "deleteUsers",
"tags": ["users"],
"parameters": [],
"responses": {
"204": {
"description": "Users were successfully deleted."
}
}
},
"post": {
"description": "Create a new user.",
"operationId": "createUser",
"tags": [
"users",
"creating"
],
"parameters": [],
"responses": {
"default": {
"description": "Unexpected error",
"schema": {
"$ref": "#/definitions/Error"
}
}
}
}
},
"/users/{id}": {
"parameters": [
{
"description": "Fred's age.",
"in": "path",
"name": "id",
"required": true,
"type": "string"
}
],
"get": {
"description": "Retrieve a user.",
"operationId": "getUser",
"parameters": [
{
"description": "The name of this person. It may only be \"fred\".",
"in": "query",
"name": "name",
"pattern": "^fred$",
"type": "string"
},
{
"description": "Fred's age.",
"in": "path",
"name": "id",
"required": true,
"type": "integer"
},
{
"default": 80,
"description": "Fred's age.",
"in": "query",
"name": "age",
"type": "integer"
}
],
"responses": {
"200": {
"description": "Requested user",
"schema": {
"$ref": "#/definitions/User"
}
},
"default": {
"description": "Unexpected error",
"schema": {
"$ref": "#/definitions/Error"
}
}
},
"tags": [
"users",
"fooey"
]
},
"post": {
"description": "Create a user.",
"operationId": "createUser",
"parameters": [
{
"in": "body",
"name": "user",
"schema": {
"$ref": "#/definitions/User"
}
}
],
"responses": {
"default": {
"description": "Unexpected error",
"schema": {
"$ref": "#/definitions/Error"
}
}
},
"tags": [
"users"
]
}
}
},
"swagger": "2.0",
"tags": [
{
"name": "creating"
},
{
"name": "fooey"
},
{
"description": "Everything users",
"name": "users"
}
],
"x-express-openapi-schema-extension": {
"definitions": {
"schema": {
"properties": {
"oneOf": {
"type": "array",
"minItems": 1,
"items": {
"$ref": "#/definitions/schema"
}
}
}
}
}
}
}
Loading

0 comments on commit f13f11c

Please sign in to comment.