From 305d5db93f88f4117441834e7b5d9ae14545d115 Mon Sep 17 00:00:00 2001 From: Arno Hilke Date: Sat, 13 Mar 2021 02:46:38 +0100 Subject: [PATCH] doc: Clean up README and Nestjs Example (#559) * doc: Remove Q&A for Upgrade from v2 to v3 The `installSync` method and `synchronous` README section mentioned in the answer no longer exist in v4. * doc: Fix Typos in README * doc: Remove Vestiges of Config Module from NestJS Example --- README.md | 32 +++++++++----------- examples/9-nestjs/package-lock.json | 45 ++++------------------------- examples/9-nestjs/package.json | 3 +- examples/9-nestjs/src/app.module.ts | 3 +- 4 files changed, 22 insertions(+), 61 deletions(-) diff --git a/README.md b/README.md index cc9530b7..2bf9349c 100644 --- a/README.md +++ b/README.md @@ -172,7 +172,7 @@ Use express-openapi-validator's OpenAPI `x-eov-operation-*` vendor extensions. S **Here's the gist** -- First, specifiy the `operationHandlers` option to set the base directory that contains your operation handler files. +- First, specify the `operationHandlers` option to set the base directory that contains your operation handler files. ```javascript app.use( @@ -205,7 +205,7 @@ app.use( ```javascript module.exports = { - // the express handler implementaiton for ping + // the express handler implementation for ping ping: (req, res) => res.status(200).send('pong'), }; ``` @@ -275,7 +275,7 @@ module.exports = app; # OpenAPI's operationId may be used to to specify the operation id operationId: ping # x-eov-operation-id may be used to specify the operation id - # Used when operationId is omiited. Overrides operationId when both are specified + # Used when operationId is omitted. Overrides operationId when both are specified x-eov-operation-id: ping # specifies the path to the operation handler. # the path is relative to the operationHandlers option @@ -518,7 +518,7 @@ OpenApiValidator.middleware({ ### ▪️ apiSpec (required) -Specifies the path to an OpenAPI 3 specification or a JSON object representing the OpenAPI 3 specificiation +Specifies the path to an OpenAPI 3 specification or a JSON object representing the OpenAPI 3 specification ```javascript apiSpec: './path/to/my-openapi-spec.yaml'; @@ -600,7 +600,7 @@ Determines whether the validator should validate requests. **removeAdditional:** - Determines whether to keep or remove additional properties in request body or to fail validation if schema has `additionalProperties` set to `false`. For futher details, refer to [AJV documentation](https://ajv.js.org/docs/validation.html#removing-additional-properties) + Determines whether to keep or remove additional properties in request body or to fail validation if schema has `additionalProperties` set to `false`. For further details, refer to [AJV documentation](https://ajv.js.org/docs/validation.html#removing-additional-properties) - `false` (**default**) - not to remove additional properties - `"all"` - all additional properties are removed, regardless of additionalProperties keyword in schema (and no validation is made for them). @@ -683,14 +683,14 @@ Determines whether the validator should validate securities e.g. apikey, basic, Determines whether the validator should validate the OpenAPI specification. Useful if you are certain that the api spec is syntactically correct and want to bypass this check. -*Warning:* e certain your spec is valid. And be sure you know what you're doing! express-openapi-validator _*expects*_ are valid spec. If incorrect, the validator will behave erradically and/or throw Javascript errors. +*Warning:* Be certain your spec is valid. And be sure you know what you're doing! express-openapi-validator _*expects*_ a valid spec. If incorrect, the validator will behave erratically and/or throw Javascript errors. - `true` (**default**) - validate the OpenAPI specification. - `false` - do not validate the OpenAPI specification. ### ▪️ formats (optional) -Defines a list of custome formats. +Defines a list of custom formats. - `[{ ... }]` - array of custom format objects. Each object must have the following properties: - name: string (required) - the format name @@ -728,7 +728,7 @@ my_property: Specifies the strictness of validation of string formats. -- `"fast"` (**default**) - only validate syntax, but not semantics. E.g. `2010-13-30T23:12:35Z` will pass validation eventhough it contains month 13. +- `"fast"` (**default**) - only validate syntax, but not semantics. E.g. `2010-13-30T23:12:35Z` will pass validation even though it contains month 13. - `"full"` - validate both syntax and semantics. Illegal dates will not pass. - `false` - do not validate formats at all. @@ -796,7 +796,7 @@ See [mongo-serdes-js](https://github.com/pilerou/mongo-serdes-js) for additional Defines the base directory for operation handlers. This is used in conjunction with express-openapi-validator's OpenAPI vendor extensions, `x-eov-operation-id`, `x-eov-operation-handler` and OpenAPI's `operationId`. See [example](https://github.com/cdimascio/express-openapi-validator/tree/master/examples/3-eov-operations). -Additionally, if you want to change how modules are resolved e.g. use dot deliminted operation ids e.g. `path.to.module.myFunction`, you may optionally add a custom `resolver`. See [documentation and example](https://github.com/cdimascio/express-openapi-validator/tree/master/examples/5-custom-operation-resolver) +Additionally, if you want to change how modules are resolved e.g. use dot delimited operation ids e.g. `path.to.module.myFunction`, you may optionally add a custom `resolver`. See [documentation and example](https://github.com/cdimascio/express-openapi-validator/tree/master/examples/5-custom-operation-resolver) - `string` - the base directory containing operation handlers - `false` - (default) disable auto wired operation handlers @@ -833,7 +833,7 @@ Complete example [here](https://github.com/cdimascio/express-openapi-validator/t # OpenAPI's operationId may be used to to specify the operation id operationId: ping # x-eov-operation-id may be used to specify the operation id - # Used when operationId is omiited. Overrides operationId when both are specified + # Used when operationId is omitted. Overrides operationId when both are specified x-eov-operation-id: ping # specifies the path to the operation handler. # the path is relative to the operationHandlers option @@ -909,7 +909,7 @@ $refParser: { ### ▪️ coerceTypes (optional) - _deprecated_ -Determines whether the validator should coerce value types to match the those defined in the OpenAPI spec. This option applies **only** to path params, query strings, headers, and cookies. _It is **highly unlikley** that will want to disable this. As such this option is deprecated and will be removed in the next major version_ +Determines whether the validator should coerce value types to match the those defined in the OpenAPI spec. This option applies **only** to path params, query strings, headers, and cookies. _It is **highly unlikely** that you will want to disable this. As such this option is deprecated and will be removed in the next major version_ - `true` (**default**) - coerce scalar data types. - `"array"` - in addition to coercions between scalar types, coerce scalar data to an array with one element and vice versa (as required by the schema). @@ -939,7 +939,7 @@ In some cases, it may be necessary to _**skip validation** for paths **under the ## Security handlers -> **Note:** security `handlers` are an optional component. security `handlers` provide a convenience, whereby the request, declared scopes, and the security schema itself are provided as parameters to each security `handlers` callback that you define. The code you write in each callback can then perform authentication and authorization checks. **_Note that the same can be achieved using standard Express middleware_. The difference** is that security `handlers` provide you the OpenAPI schema data described in your specification\_. Ulimately, this means, you don't have to duplicate that information in your code. +> **Note:** security `handlers` are an optional component. security `handlers` provide a convenience, whereby the request, declared scopes, and the security schema itself are provided as parameters to each security `handlers` callback that you define. The code you write in each callback can then perform authentication and authorization checks. **_Note that the same can be achieved using standard Express middleware_. The difference** is that security `handlers` provide you the OpenAPI schema data described in your specification\_. Ultimately, this means, you don't have to duplicate that information in your code. > All in all, security `handlers` are purely optional and are provided as a convenience. @@ -1144,7 +1144,7 @@ module.exports = app; **A:** OpenAPI 3.0 does not support RFC-6570. That said, we provide a minimalistic mechanism that conforms syntactically to OpenAPI 3 and accomplishes a common use case. For example, matching file paths and storing the matched path in `req.params` -Using the following OpenAPI 3.x defintion +Using the following OpenAPI 3.x definition ```yaml /files/{path}*: @@ -1157,7 +1157,7 @@ Using the following OpenAPI 3.x defintion type: string ``` -With the following Express route defintion +With the following Express route definition ```javascript app.get(`/files/:path(*)`, (req, res) => { /* do stuff */ }` @@ -1194,10 +1194,6 @@ properties: type: string ``` -**Q:** I upgraded from from v2 to v3 and validation no longer works. How do I fix it? - -**A**: In version 2.x.x, the `install` method was executed synchronously, in 3.x it's executed asynchronously. To get v2 behavior in v3, use the `installSync` method. See the [synchronous](#synchronous) section for details. - **Q:** Can I use `express-openapi-validator` with `swagger-ui-express`? **A:** Yes. Be sure to `use` the `swagger-ui-express` serve middleware prior to installing `OpenApiValidator`. This will ensure that `swagger-ui-express` is able to fully prepare the spec before before OpenApiValidator attempts to use it. For example: diff --git a/examples/9-nestjs/package-lock.json b/examples/9-nestjs/package-lock.json index 7044d705..ca6115d5 100644 --- a/examples/9-nestjs/package-lock.json +++ b/examples/9-nestjs/package-lock.json @@ -919,19 +919,6 @@ "uuid": "8.3.2" } }, - "@nestjs/config": { - "version": "0.6.3", - "resolved": "https://registry.npmjs.org/@nestjs/config/-/config-0.6.3.tgz", - "integrity": "sha512-JxvvUpmH0/WOrTB+zh8dEkxSUQXhB7V3d/qeQXyCnMiEFjaq89+fNFztpWjz4DlOfdS4/eYTzIEy9PH2uGnfzA==", - "requires": { - "dotenv": "8.2.0", - "dotenv-expand": "5.1.0", - "lodash.get": "4.4.2", - "lodash.has": "4.5.2", - "lodash.set": "4.3.2", - "uuid": "8.3.2" - } - }, "@nestjs/core": { "version": "7.6.13", "resolved": "https://registry.npmjs.org/@nestjs/core/-/core-7.6.13.tgz", @@ -1227,9 +1214,9 @@ "dev": true }, "@types/qs": { - "version": "6.9.5", - "resolved": "https://registry.npmjs.org/@types/qs/-/qs-6.9.5.tgz", - "integrity": "sha512-/JHkVHtx/REVG0VVToGRGH2+23hsYLHdyG+GrvoUGlGAd0ErauXDyvHtRI/7H7mzLm+tBCKA7pfcpkQ1lf58iQ==" + "version": "6.9.6", + "resolved": "https://registry.npmjs.org/@types/qs/-/qs-6.9.6.tgz", + "integrity": "sha512-0/HnwIfW4ki2D8L8c9GVcG5I72s9jP5GSLVF0VIXDW00kmIpA6O33G7a8n59Tmh7Nz0WUC3rSb7PTY/sdW2JzA==" }, "@types/range-parser": { "version": "1.2.3", @@ -2664,16 +2651,6 @@ } } }, - "dotenv": { - "version": "8.2.0", - "resolved": "https://registry.npmjs.org/dotenv/-/dotenv-8.2.0.tgz", - "integrity": "sha512-8sJ78ElpbDJBHNeBzUbUVLsqKdccaa/BXF1uPTw3GrvQTBgrQrtObr2mUrE38vzYd8cEv+m/JBfDLioYcfXoaw==" - }, - "dotenv-expand": { - "version": "5.1.0", - "resolved": "https://registry.npmjs.org/dotenv-expand/-/dotenv-expand-5.1.0.tgz", - "integrity": "sha512-YXQl1DSa4/PQyRfgrv6aoNjhasp/p4qs9FjJ4q4cQk+8m4r6k4ZSiEyytKG8f8W9gi8WsQtIObNmKd+tMzNTmA==" - }, "ecc-jsbn": { "version": "0.1.2", "resolved": "https://registry.npmjs.org/ecc-jsbn/-/ecc-jsbn-0.1.2.tgz", @@ -2967,9 +2944,9 @@ } }, "express-openapi-validator": { - "version": "4.12.1", - "resolved": "https://registry.npmjs.org/express-openapi-validator/-/express-openapi-validator-4.12.1.tgz", - "integrity": "sha512-RqJeX3gA8cI2KnDIJb5VGZ/rI5zmFjVX5AxtkJH1m8FaHACuOaEso9PxHQzlJ5g2tvOIAXSTdxQBK4w60+7omw==", + "version": "4.12.4", + "resolved": "https://registry.npmjs.org/express-openapi-validator/-/express-openapi-validator-4.12.4.tgz", + "integrity": "sha512-+dQ/zPC7em9TLKP9BsFUBJxk2XuWg1mofYAk+ZwwM3+xEzV4MZ1/kpdoc5n9QxYu6B5sWzerc+J6XULJ/j7K9A==", "requires": { "@types/multer": "^1.4.5", "ajv": "^6.12.6", @@ -4591,16 +4568,6 @@ "resolved": "https://registry.npmjs.org/lodash.get/-/lodash.get-4.4.2.tgz", "integrity": "sha1-LRd/ZS+jHpObRDjVNBSZ36OCXpk=" }, - "lodash.has": { - "version": "4.5.2", - "resolved": "https://registry.npmjs.org/lodash.has/-/lodash.has-4.5.2.tgz", - "integrity": "sha1-0Z9NwQlQWMzL4rDN9O4P5Ko3yGI=" - }, - "lodash.set": { - "version": "4.3.2", - "resolved": "https://registry.npmjs.org/lodash.set/-/lodash.set-4.3.2.tgz", - "integrity": "sha1-2HV7HagH3eJIFrDWqEvqGnYjCyM=" - }, "lodash.sortby": { "version": "4.7.0", "resolved": "https://registry.npmjs.org/lodash.sortby/-/lodash.sortby-4.7.0.tgz", diff --git a/examples/9-nestjs/package.json b/examples/9-nestjs/package.json index 562c8484..0818d34e 100644 --- a/examples/9-nestjs/package.json +++ b/examples/9-nestjs/package.json @@ -19,10 +19,9 @@ }, "dependencies": { "@nestjs/common": "^7.6.12", - "@nestjs/config": "^0.6.3", "@nestjs/core": "^7.6.12", "@nestjs/platform-express": "^7.6.12", - "express-openapi-validator": "^4.10.11", + "express-openapi-validator": "^4.12.4", "reflect-metadata": "^0.1.13", "rxjs": "^6.6.3", "shx": "^0.3.3" diff --git a/examples/9-nestjs/src/app.module.ts b/examples/9-nestjs/src/app.module.ts index 9c7c5373..a3a36ee3 100644 --- a/examples/9-nestjs/src/app.module.ts +++ b/examples/9-nestjs/src/app.module.ts @@ -1,5 +1,4 @@ import { MiddlewareConsumer, Module, NestModule } from '@nestjs/common'; -import { ConfigModule } from '@nestjs/config'; import { APP_FILTER } from '@nestjs/core'; import * as OpenApiValidator from 'express-openapi-validator'; import { join } from 'path'; @@ -7,7 +6,7 @@ import { PingModule } from './modules/ping/ping.module'; import { OpenApiExceptionFilter } from './filters/openapi-exception.filter'; @Module({ - imports: [ConfigModule.forRoot(), PingModule], + imports: [PingModule], providers: [{ provide: APP_FILTER, useClass: OpenApiExceptionFilter }], }) export class AppModule implements NestModule {