Use api docs properly

Closes Issue #23 
Closes Issue #19 

This change moves pyramid_swagger to read from a combination of a resource listing and an associated set of api declarations.

- the acceptance tests are now pulled from N>1 distinct API Declarations
- terminology has been cleaned up significantly in the code itself to better reflect the accepted vocabulary
- documentation has been appropriately updated
Added in the follow up branch (where these change a fair bit)