make failures on api_samples more clear
make failures on api_samples more clear

This changes the failure mode for api_samples in 2 ways. The first of
which is it pretty prints the 2 documents that are compared whenever
there is a failure. This makes finding the differences by eye a lot
easier.

Secondly, it adds a short circuit when comparing lists, if they are
both of length 1. The list comparison is weird, and you get very
unhelpful error messages if you are comparing 2 lists of length 1 and
one has extra keys. It doesn't help all situations, but this is pretty
common, so will make these a ton easier to figure out what's wrong.

All of this is extremely helpful in figuring out what you did wrong in
decomposing an API extension. And thus is part of

blueprint api-no-more-extensions

Change-Id: I5f487c6798485a58cc020723dd5e880720c51bed

openstack/nova,openstack/nova,cloudbase/nova,sebrandon1/nova,mahak/nova,rajalokan/nova,rajalokan/nova,rajalokan/nova,rahulunair/nova,klmitch/nova,Juniper/nova,jianghuaw/nova,Juniper/nova,jianghuaw/nova,cloudbase/nova,mikalstill/nova,rahulunair/nova,sebrandon1/nova,gooddata/openstack-nova,phenoxim/nova,vmturbo/nova,vmturbo/nova,Juniper/nova,mikalstill/nova,mikalstill/nova,mahak/nova,hanlind/nova,vmturbo/nova,alaski/nova,mahak/nova,rahulunair/nova,gooddata/openstack-nova,gooddata/openstack-nova,gooddata/openstack-nova,Juniper/nova,vmturbo/nova,klmitch/nova,alaski/nova,jianghuaw/nova,cloudbase/nova,phenoxim/nova,hanlind/nova,jianghuaw/nova,klmitch/nova,klmitch/nova,rajalokan/nova,sebrandon1/nova,hanlind/nova,openstack/nova