Document why we don't allow shared object definitions to be reused in api.yaml

Document why we don't allow shared object definitions to be reused in api.yaml #2487