I\'m trying to figure out the best way to have my API documentation be the source of truth and use it to validate the actual Java REST code ideally through integration testi
You may want to look at Spring Cloud Contract. It offers you a DSL, where you can describe the scenarios (more or less what is the response I get for a given request) and it seems to fit well to what you described as a requirement...
Recently, we (swagger-codegen community) start adding automatic test case generation to API clients (C#, PHP, Ruby). We've not added that to Java yet. Here are some example test cases generated by Swagger-Codegen for C#:
https://github.com/swagger-api/swagger-codegen/tree/master/samples/client/petstore/csharp/SwaggerClient/src/IO.Swagger.Test
It's still very preliminary and we would like to hear feedback from you to see if that's what you're looking for.
I think you should try swagger-request-validator: https://bitbucket.org/atlassian/swagger-request-validator
Here are some examples how to use it: https://bitbucket.org/atlassian/swagger-request-validator/src/master/swagger-request-validator-examples/
Another alternative is assertj-swagger: https://github.com/RobWin/assertj-swagger
If you're using the Spring Framework, I'd highly recommend checking out Spring RestDocs which allow you to generate