Add examples of production usage

[James Navin]

Currently the examples project only contains example usage of the validator for testing.

It would be good to add examples of using the validator in a production use case.

[Adrien Petitjean]

@jfnavin yes would be nice to have, is there any example of an implementation with Jersey / Spring ?

I am quiet new with java, and I am building an api, documented with swagger, I want to do some validation on the request coming to my api, I am guessing that I need to build something based on this example : https://bitbucket.org/atlassian/swagger-request-validator/src/60956b0eb42a3c51c4111bdc4390c925ab90b3fa/swagger-request-validator-core/?at=master probably add a interceptor like this http://www.journaldev.com/2676/spring-mvc-interceptor-example-handlerinterceptor-handlerinterceptoradapter and within this interceptor do create an implementation of this https://bitbucket.org/atlassian/swagger-request-validator/src/60956b0eb42a3c51c4111bdc4390c925ab90b3fa/swagger-request-validator-core/src/main/java/com/atlassian/oai/validator/model/Request.java?at=master&fileviewer=file-view-default from the HttpServletRequest Object, and finally call the validateRequest method Am I right ?

[James Navin]

That sounds like the right approach, yes.

Some things you would probably want to think about:

• Do you want to return a 400 if the request is invalid?
• Do you want to fail the request if the response is invalid? or let it through and log something?
• How much information do you want to send back to the Consumer? Do response validation messages make any sense for the Consumer?

If you were interested, an interceptor like that would probably be useful to others - you could add it to a new module in this project (e.g. swagger-request-validator-springmvc - see the contributor notes in the README for how to contribute). Otherwise I might look at adding something like it at some point (when I get some time...)

[Sven Döring]

I already implemented this for work.

As the Swagger Request Validator is not directly supported by Spring there are two reasonable ways to add the SRV to Spring. Both have caveats, partly the same.

1. Use a filter to validate the requests.
2. Use an interceptor to validate the requests.

The biggest challenge is the ServletInputStream those body can only be read once. As the SRV needs the body to validate its content the Spring MVC mapping can't access the body again. This is bad, obviously, because Spring can't unmarshall the request body and an Exception is thrown.

Every approach to this challenge is a bit nasty. I created a ResettableServletInputStream, which caches the request body on its first readout. Than resetting it and on the next access the cache is readout. Spring MVC can than unmarshall the request body. The ContentCachingRequestWrapper from Spring was a huge help for that undertaking.

I decided to use an Interceptor. In case of an invalid request I throw an InvalidRequestException which is mapped to the HTTP Status Code 400. Spring MVC than marshalls the exception into a JSON error including the validation messages from SRV. I decided against the Filter, which was my first approach, because the exception handling is missing for filters. So no automatic Status Code mapping, no automatic exception marshalling, etc.

I did not use response validation. It seemed a bit strange. If the response does not fit the API definition there is a bug in the web service, which should be fixed. Or the API definition is wrong, so this should be fixed. I think the response should be validated on the client not on the server. It could be used as internal support for finding bugs, though.

[Sven Döring]

I would like to create a subtask for implementing an easy to use interceptor for usage in Spring REST services assigned to me.

[James Navin]

Excellent! I'll raise a ticket.

[James Navin]

A Spring MVC module has been implemented along with example usage for validating production requests - see #51