Add code-derived OpenAPI 3.0 spec for Supermarket API v1

[Copilot]

This PR adds an accurate OpenAPI specification for Chef Supermarket’s API surface based on current routes/controllers/views, replacing drift-prone interpretation with code-aligned contract documentation. The spec captures implemented behavior, including aliases, auth expectations, payload shapes, and known legacy endpoints.

• Scope captured (API surface)

  • Documents all active v1 endpoints under /api/v1 plus route aliases (/universe, /api/v1/universe, /status).
  • Includes cookbook, cookbook-version, tools, users, search, health, metrics, and quality-metric endpoints.

• Contract details encoded

  • Defines query/path params (start, items, order, platforms[], version, etc.) and documented constraints/defaults.
  • Models response bodies from Jbuilder/controller output, including list/detail schemas and shared error envelope.
  • Represents redirect semantics for version downloads (302 with Location).

• Auth and feature behavior

  • Adds security schemes for signed Chef upload requests and fieri_key-guarded quality-metric endpoints.
  • Marks legacy/compatibility quality-metric routes as deprecated where applicable.

• Artifact added

  • src/supermarket/docs/supermarket-api-v1.openapi.yaml

paths:
  /api/v1/cookbooks/{cookbook}/versions/{version}/download:
    get:
      responses:
        "302":
          description: Redirect to artifact URL
          headers:
            Location:
              schema:
                type: string
                format: uri