Add initial OpenAPI (Swagger) specification for OpenCRE REST API

[PRAteek-singHWY]

Related issue

Addresses: #295 — Create Swagger or .proto definition for the OpenCRE API

---

Summary

This PR introduces an initial OpenAPI (Swagger) specification for the existing OpenCRE REST API.

As OpenCRE adoption grows, external users increasingly request SDKs, clients, and other programmatic integrations. Until now, the API surface has only been discoverable through the frontend or by reading backend source code. This PR provides a formal, machine-readable definition of the currently exposed REST endpoints.

---

What this PR does

• Adds an OpenAPI 3.0.1 specification at docs/api/openapi.yaml
• Documents the existing public, read-only /rest/v1/* GET endpoints
• Captures supported query parameters and optional response formats as implemented today
• Enables downstream use cases such as:
  • Client / SDK generation
  • API discovery
  • External integrations

---

What this PR does NOT do

This PR is intentionally conservative and documentation-only:

• ❌ No backend or runtime changes
• ❌ No new endpoints
• ❌ No authentication flows
• ❌ No Swagger UI or spec serving
• ❌ No deep or opinionated response schema modeling

The goal is to document current behavior, not redesign the API.

---

Why this approach

Starting with a minimal, accurate OpenAPI spec:

• Keeps review scope small and safe
• Avoids accidental API contract changes
• Creates a clear foundation for incremental improvements in follow-up PRs
  (e.g. richer schemas, examples, serving the spec, or client generation)

[PRAteek-singHWY]

Hey @northdpole — for context, I looked through the repo and existing docs and didn’t find a formal OpenAPI / Swagger / proto definition for the REST API. This PR documents the currently implemented /rest/v1/* endpoints as they exist today, in line with #295.

If there’s prior work, a different preferred format, or a specific direction you’d like this to evolve toward, I’m happy to align.