exegesis-express
Advanced tools
exegesis-express - npm Package Compare versions
Comparing version 1.0.0-rc1 to 1.0.0
| { | ||
| "name": "exegesis-express", | ||
| "version": "1.0.0-rc1", | ||
| "version": "1.0.0", | ||
| "description": "Express middleware to handle OpenAPI 3.x.", | ||
@@ -20,3 +20,3 @@ "main": "dist/index.js", | ||
| "lint:tests": "tslint -c test/tslint.json -t stylish 'test/**/*.ts'", | ||
| "lint:markdown": "markdownlint src/**/*.md *.md", | ||
| "lint:markdown": "markdownlint src/**/*.md README.md", | ||
| "prepare": "npm run build", | ||
@@ -62,3 +62,3 @@ "prepublishOnly": "npm run build && npm test", | ||
| "@types/chai": "^4.1.3", | ||
| "exegesis": "^1.0.0-rc1" | ||
| "exegesis": "^1.0.0" | ||
| }, | ||
@@ -76,3 +76,3 @@ "devDependencies": { | ||
| "lint-staged": "^7.1.0", | ||
| "markdownlint-cli": "^0.8.2", | ||
| "markdownlint-cli": "^0.9.0", | ||
| "mocha": "^5.1.1", | ||
@@ -79,0 +79,0 @@ "nyc": "^11.7.2", |
110
README.md
@@ -18,44 +18,40 @@ # exegesis-express | ||
| ## WARNING | ||
| ## Features | ||
| 🚨🚨 This is super beta. 🚨🚨 | ||
| * Full support for OpenAPI 3.x.x (see [issues tagged with conformance](https://github.com/exegesis-js/exegesis/issues?q=is%3Aissue+is%3Aopen+label%3Aconformance) for areas which could use some improvement). | ||
| * Built in support for "application/json" and "application/x-www-form-urlencoded" requests | ||
| * Can use express [body parser middlewares](https://github.com/exegesis-js/exegesis/blob/master/docs/Options.md#mimetypeparsers) | ||
| * [Response validation](https://github.com/exegesis-js/exegesis/blob/master/docs/Options.md#onresponsevalidationerror) | ||
| * [Authentication support](https://github.com/exegesis-js/exegesis/blob/master/docs/OAS3%20Security.md) | ||
| * [Plugins](https://github.com/exegesis-js/exegesis/tree/master/docs) allow easy extensibility | ||
| * Easy support for [validating custom formats](https://github.com/exegesis-js/exegesis/blob/master/docs/Options.md#customformats) | ||
| This is very much a work in progress. Wait for the v1.0.0 release, coming soon! :) | ||
| ## Tutorial | ||
| Check out the tutorial [here](https://github.com/exegesis-js/exegesis/blob/master/docs/Tutorial.md). | ||
| ## Usage | ||
| ```js | ||
| import express from 'express'; | ||
| import http from 'http'; | ||
| import * as exegesisExpress from 'exegesis-express'; | ||
| Calling `exegesisExpress.middleware(openApiFile, options)` will return a Promise | ||
| which resolves to a connect/express middleware (alternatively you can call | ||
| `exegesisExpress.middleware(openApiFile, options, done)`, if callbacks are your | ||
| thing). | ||
| async function createServer() { | ||
| // See https://github.com/exegesis-js/exegesis/blob/master/docs/Options.md | ||
| const options { | ||
| controllers: path.resolve(__dirname, './controllers') | ||
| }; | ||
| `openApiFile` is either a path to your openapi.yaml or openapi.json file, | ||
| or it can be a JSON object with the contents of your OpenAPI document. This | ||
| should have the [`x-exegesis-controller`](https://github.com/exegesis-js/exegesis/blob/master/docs/OAS3%20Specification%20Extensions.md) | ||
| extension defined on any paths you want to be able to access. | ||
| const exegesisMiddleware = await exegesisExpress.middleware( | ||
| path.resolve(__dirname, './openapi.yaml'), | ||
| options | ||
| ); | ||
| `options` can be [anything you can pass to exegesis](https://github.com/exegesis-js/exegesis/blob/master/docs/Options.md). At a | ||
| minimum, you'll probably want to provide `options.controllers`, a path to where | ||
| your [controller modules](https://github.com/exegesis-js/exegesis/blob/master/docs/Exegesis%20Controllers.md) | ||
| can be found. If you have any security requirements defined, you'll also | ||
| want to pass in some [authenticators](https://github.com/exegesis-js/exegesis/blob/master/docs/OAS3%20Security.md). | ||
| To enable response validation, you'll want to provide a validation callback | ||
| function via [`onResponseValidationError()`](https://github.com/exegesis-js/exegesis/blob/master/docs/Options.md#onresponsevalidationerror). | ||
| Exegesis's functionality can also be extended using [plugins](https://github.com/exegesis-js/exegesis/tree/master/docs), | ||
| which run on every request. Plugins let you add functionality like | ||
| [role base authorization](https://github.com/exegesis-js/exegesis-plugin-roles), | ||
| or CORS. | ||
| const app = express(); | ||
| // If you have any body parsers, this should go before them. | ||
| app.use(exegesisMiddleware); | ||
| app.use((req, res) => { | ||
| res.status(404).json({message: `Not found`}); | ||
| }); | ||
| app.use((err, req, res, next) => { | ||
| res.status(500).json({message: `Internal error: ${err.message}`}); | ||
| }); | ||
| const server = http.createServer(app); | ||
| server.listen(3000); | ||
| } | ||
| ``` | ||
| ## Where to put Exegesis-Express in your middleware stack | ||
@@ -65,4 +61,4 @@ | ||
| any body parsers. This is because exegesis will take care of parsing the body | ||
| for us, and it can't do that if the body has already been read. If you put | ||
| a body parser ahead of exeges-express, exegesis will try to use `req.body` | ||
| for you, and it can't do that if the body has already been read. If you put | ||
| a body parser ahead of exegesis-express, exegesis will try to use `req.body` | ||
| if it's there. | ||
@@ -101,9 +97,41 @@ | ||
| ## TODO | ||
| ## Example | ||
| * [ ] Enable semantic-release | ||
| * `travis env set GH_TOKEN [your token here]` | ||
| * `travis env set NPM_TOKEN [your token here]` | ||
| * Uncomment lines in travis.yml | ||
| ```js | ||
| import express from 'express'; | ||
| import path from 'path'; | ||
| import http from 'http'; | ||
| import * as exegesisExpress from 'exegesis-express'; | ||
| async function createServer() { | ||
| // See https://github.com/exegesis-js/exegesis/blob/master/docs/Options.md | ||
| const options = { | ||
| controllers: path.resolve(__dirname, './controllers') | ||
| }; | ||
| const exegesisMiddleware = await exegesisExpress.middleware( | ||
| path.resolve(__dirname, './openapi.yaml'), | ||
| options | ||
| ); | ||
| const app = express(); | ||
| // If you have any body parsers, this should go before them. | ||
| app.use(exegesisMiddleware); | ||
| app.use((req, res) => { | ||
| res.status(404).json({message: `Not found`}); | ||
| }); | ||
| app.use((err, req, res, next) => { | ||
| res.status(500).json({message: `Internal error: ${err.message}`}); | ||
| }); | ||
| const server = http.createServer(app); | ||
| server.listen(3000); | ||
| } | ||
| ``` | ||
| --- | ||
| Copyright 2018 Jason Walton |
New alerts
License Policy Violation
LicenseThis package is not allowed per your license policy. Review the package's license to ensure compliance.
Found 1 instance in 1 package
Fixed alerts
License Policy Violation
LicenseThis package is not allowed per your license policy. Review the package's license to ensure compliance.
Found 1 instance in 1 package
No v1
QualityPackage is not semver >=1. This means it is not stable and does not support ^ ranges.
Found 1 instance in 1 package
Improved metrics
- Total package byte prevSize
- increased by28.45%
10575
- Number of low quality alerts
- decreased by-100%
0
- Number of lines in readme file
- increased by26.17%
135
Dependency changes
Updatedexegesis@^1.0.0