Updated the docs. Added sections on caching and Swagger support.

I updated the docs in light of the introduction of the caching layer and the support for Swagger docs.

However I have a PR that could change the usage of `api:swagger:docs` which I think we should consider: https://github.com/nelmio/NelmioApiDocBundle/pull/455