Clarify which PATCH requests add vs. overwrite

[kaganjd]

We had an enterprise customer who was surprised when their PATCH request to update environment variables actually overwrote their existing variables. They said:

I made this patch request, expecting only the named environment variables to be updated. Instead, the entire env block was replaced.

The API call was curl --location --request PATCH 'https://api.netlify.com/api/v1/sites/:site_id' with payload

"build_settings": {
        "env": {
            "KEY": "VALUE"
        }

which resulted in replacing several variables with just this one new one, KEY=VALUE

[keiko713]

Because the env there is nested, we did the PATCH that level, to only update env (not other build settings). However, I agree that this is confusing behavior. We are working on improving the Open API doc, I think this is something we could document well in the doc for the next generation one, to explain how it exactly works.
Alternatively, we could create a separate endpoint specific to update/patch the env, but that'll be a feature request.