[Docs] add response example for bulk entities upload

[spwoodcock]

Issue

• Currently the docs for POST /projects/{projectId}/datasets/{name}/entities show the response type for uploading a single Entity.
• They have not been updated to show the response type when bulk uploading multiple Entities.
• Ideally the response would return the Entity data, but this is not trivial, due to having to re-fetch data from the db for each Entity (line 98 & 113):
  

  central-backend/lib/resources/entities.js

  Lines 93 to 114 in fb96aa3

  	if (!entities) {
  	// not a bulk operation
  	const partial = await Entity.fromJson(body, properties, dataset);
  	const sourceId = await Entities.createSource();
  	const entity = await Entities.createNew(dataset, partial, null, sourceId, userAgent);
  	// Entities.createNew doesn't return enough information for a full response so re-fetch.
  	return Entities.getById(dataset.id, entity.uuid).then(getOrNotFound);
  	} else {
  	// bulk operation
  	if (!Array.isArray(body.entities))
  	return reject(Problem.user.unexpectedAttributes({ expected: ['entities: [...]'], actual: ['not an array'] }));
  	if (!body.entities.length)
  	return reject(Problem.user.unexpectedAttributes({ expected: ['entities: [...]'], actual: ['empty array'] }));
  	const partials = body.entities.map(e => Entity.fromJson(e, properties, dataset));
  	const sourceId = await Entities.createSource(extractBulkSource(source, partials.length, userAgent));
  	await Entities.createMany(dataset, partials, sourceId, userAgent);
  	return success();
  	}

Solution

• The endpoint currently returns 'success': true.
• I updated the docs to reflect this, until the endpoint returns the Entity data (if possible).
• I reused the pattern in the docs for return type application/json; extended to use application/json; bulk, allowing us to display two examples side-by-side - not sure if this is the preferred approach!

[matthew-white]

Thank you, @spwoodcock! I definitely agree that it's useful to document this response.