update the code samples to be up-to-date with CORS/proxy/etc settings
Activating CORS under Settings doesn't seem to change the code samples, which I find rather important for transparency.
CORS samples are returned, not requested, so it should be OK this way.
Mock/proxy settings will be separated by using different urls.
AdminApiary (Admin, apiary.io) commented
Right, I see your point…
Original request for CORS headers was to allow easy browser-based experimenting with the API. Later in the development, the real API (not our mock server) might not necessarily be serving CORS headers anymore.
Thus we chose to make a concession and server CORS headers (if turned on) without documenting them. The documentation should only contain behavior of the real API.
It's a slightly dirty, one-off approach. The other option (forcing users to spell out CORS behavior into the blueprint) seemed a total productivity killer.
Wondering what to do about it now…
Andrei Neculau commented
basically whatever your mock server is doing when CORS is turned on should be reflected in the "documentation" tab, even though I didn't include the CORS headers in the API blueprint.
The same could go for other types of headers e.g. if the request/response has a body, include a "Content-Length" header.