Add documentation for match()

[codeclown]

Documentation proposal for feature from https://github.com/Hilzu/express-openapi-validate/pull/37

---

Maintainers, feel free to edit any formatting or words as you wish.

[coveralls]

Coverage remained the same at 100.0% when pulling 45a7b0d81712bbdf95b5c8a0df99716be9d16be2 on codeclown:match-docs into e0d7377f63da1a30fac9bfa78a715803bd165266 on Hilzu:master.

[Hilzu]

You should document what the pitfall of using match compared to validate is. With validate you get an error if you try to add validation for an operation that doesn't exists. Using match you might not have a validator even if you expect there to be one due to a typo for example.

[codeclown]

Very good point and one that I did not properly consider before. Now I would actually prefer to change the default behaviour so that an exception is thrown by match() if no validator was found for the request (could be disabled via option i.e. validator.match({ allowNoMatch: true })).

What do you think of this @Hilzu?

In regards to this PR... I'll update the docs with current state.

[Hilzu]

That might be one way of doing it.

I'm also thinking about adding a validate-like method, that needs to be explicitly added to routes but wouldn't need the operation specified. Instead it would find the validator using the same machinery as match but could error/warn if one isn't found since you explicitly asked for a validation for a route.

[codeclown]

Using match(), if it was changed to throw on unmatched route, that would be the behaviour if you used it on individual routes as well, like this:

app.get('/foo', validator.match(), (req, res, next) => ...);

But I think you're not talking about middleware? Could you illustrate with an example what you mean exactly?

[Hilzu]

No middleware is exactly what I'm talking about. Somehow I didn't realize that match could also be used like that.

I think making match throw by default and also documenting the usage with a single route is a good way forward.