fix(openapi): declare authentication via securitySchemes instead of ignored header parameters

[yingzhehu-TT]

Closes #668

Summary

• Add components.securitySchemes with oauth2_bearer (HTTP bearer) and
  api_key (X-API-Key), and a document-level security requirement.
• Remove the authorization, x_api_key, content_type and accept header
  parameter definitions and all 53 $refs to them.

Motivation

#668 reports that Authorization is declared as a header parameter, which
OpenAPI 3.1 requires implementations to ignore. The same clause covers two more
parameters in the same file that the issue does not mention:

If in is "header" and the name field is "Accept", "Content-Type" or
"Authorization", the parameter definition SHALL be ignored.
— OpenAPI 3.1.0, Parameter Object

Current state of source/services/shopping/rest.openapi.json:

Parameter	name	$refs	Ignored by OpenAPI 3.1
authorization	Authorization	13	yes — reported in #668
content_type	Content-Type	13	yes — not previously reported
accept	Accept	13	yes — not previously reported
x_api_key	X-API-Key	14	no, but it is authentication

That is 39 parameter references the specification requires tooling to discard,
and components.securitySchemes is absent from the document entirely. Anything
generated from this file — clients, validators, docs — silently drops the
authentication contract.

Content-Type and Accept need no replacement: the information is already
carried correctly and non-ignorably by the requestBody.content and
responses.*.content media-type maps, which every operation already declares.

X-API-Key is not in the ignore list, but #668 asks for "securitySchemes that
specify all supported types (i.e. JWT/OAuth, API key, basic auth, etc.)", so
leaving it as a parameter would be half a fix.

Design decisions

type: http, scheme: bearer rather than type: oauth2 with flows. The
replaced description named client_credentials and authorization_code, which
argues for type: oauth2. But an OAuth Flow Object requires concrete
tokenUrl / authorizationUrl values, and UCP has none to give: per
identity-linking.md, platforms discover the business's authorization server at
runtime via RFC 8414 metadata (OIDC fallback), and the issuer may sit on a
different origin than the business. http/bearer states exactly what is true
on the wire — Authorization: Bearer <access_token> — without fabricating fixed
endpoints. The description points readers at Identity Linking for discovery.
Happy to switch to oauth2 if the council would rather assert templated URLs.

security includes the empty requirement {}. Every parameter this PR
replaces was required: false, and signatures.md states that platforms
SHOULD sign requests and MAY use alternative mechanisms (API keys, OAuth,
mTLS) instead. So no single scheme is universally mandatory, and omitting {}
would tighten the contract beyond what the spec says.

RFC 9421 signature headers stay as parameters. Signature,
Signature-Input and Content-Digest are not in the OpenAPI ignore list, and
OpenAPI 3.1 has no security-scheme type that expresses HTTP Message Signatures.
Modelling them is a separate question and is deliberately out of scope here.

Scope

One file: source/services/shopping/rest.openapi.json (+22 / −129).

permalink.openapi.json and handlers/tokenization/openapi.json declare no
authentication headers at all, so they are untouched.

Note that x_api_key was also referenced by the orderEvent webhook; the
document-level security requirement applies to webhook operations too, so the
webhook's authentication contract is preserved rather than dropped.

Validation

• ucp-schema lint source/ — 100 files checked, all passed.
• scripts/validate_examples.py --schema-base source/schemas/ — 292 passed,
  0 failed, 0 errors, 48 skipped.
• mkdocs build --strict — completes, no warnings escalated.
• openapi-spec-validator against the built artifact shape (with info.version
  injected as hooks.py::_set_schema_version does at build time):
  VALID OpenAPI 3.1 both before and after, so document validity is preserved.
• The edit was applied by line-level surgery guarded by a structural-equality
  assertion against an independently constructed target document, so nothing
  outside the four parameters could be reordered or dropped.
• Confirmed no rendered-docs regression: main.py::method_fields explicitly
  skips in: header parameters ("Filter out headers (transport-specific)"), so
  removing them changes no generated table. The prose references to X-API-Key
  in cart-rest.md and checkout-rest.md remain accurate — these headers are
  still sent on the wire; only their OpenAPI declaration moves.

[google-cla]

Thanks for your pull request! It looks like this may be your first contribution to a Google open source project. Before we can look at your pull request, you'll need to sign a Contributor License Agreement (CLA).

View this failed invocation of the CLA check for more information.

For the most up to date status, view the checks section at the bottom of the pull request.

[yingzhehu-TT]

@googlebot I signed it!