# OpenAPI Discovery (.well-known/openapi)

As part of OAS-63-002 the platform exposes a discovery document at:

- `/.well-known/openapi` → JSON body:
  ```json
  {
    "spec": "/stella.yaml",
    "version": "v1",
    "generatedAt": "<RFC3339>",
    "extensions": {
      "x-stellaops-profile": "aggregate",
      "x-stellaops-schemaVersion": "1.0.0"
    }
  }
  ```

Contracts:
- `spec` is a relative URL to the aggregate OpenAPI (`stella.yaml`).
- `version` denotes the discovery doc version; defaults to `v1`.
- `generatedAt` is the UTC timestamp when the aggregate spec was built.
- `extensions` carries optional metadata for downstream tooling.

Implementations (API Gateway / Console) should cache the response with `Cache-Control: max-age=300` and serve it alongside the aggregate spec artifact produced by the OAS CI workflow.

---

## Gateway OpenAPI Aggregation

The Router Gateway dynamically aggregates OpenAPI documentation from connected microservices. This provides a unified API specification that updates automatically as services connect and disconnect.

### Discovery Endpoint

```http
GET /.well-known/openapi
```

**Response:**
```json
{
  "openapi_json": "/openapi.json",
  "openapi_yaml": "/openapi.yaml",
  "etag": "\"5d41402abc4b2a76b9719d911017c592\"",
  "generated_at": "2025-01-15T10:30:00.0000000Z"
}
```

### OpenAPI Endpoints

| Endpoint | Format | Content-Type |
|----------|--------|--------------|
| `GET /openapi.json` | JSON | `application/json; charset=utf-8` |
| `GET /openapi.yaml` | YAML | `application/yaml; charset=utf-8` |

### HTTP Caching

All OpenAPI endpoints support efficient caching:

| Header | Value | Description |
|--------|-------|-------------|
| `Cache-Control` | `public, max-age=60` | Client-side cache TTL |
| `ETag` | `"<hash>"` | Content hash for conditional requests |

**Conditional Request:**
```http
GET /openapi.json
If-None-Match: "5d41402abc4b2a76b9719d911017c592"
```

Returns `304 Not Modified` if content unchanged.

### Security Schemes

The Gateway generates two security schemes from endpoint claim requirements:

#### BearerAuth
```json
{
  "type": "http",
  "scheme": "bearer",
  "bearerFormat": "JWT",
  "description": "JWT Bearer token authentication"
}
```

#### OAuth2 (when endpoints have claims)
```json
{
  "type": "oauth2",
  "flows": {
    "clientCredentials": {
      "tokenUrl": "/auth/token",
      "scopes": {
        "billing:write": "Access scope: billing:write",
        "inventory:read": "Access scope: inventory:read"
      }
    }
  }
}
```

### Schema Prefixing

Schemas are prefixed with the service name to avoid collisions:

- `billing` service + `CreateInvoiceRequest` type = `billing_CreateInvoiceRequest`

### Configuration

See [OpenAPI Aggregation](../modules/router/openapi-aggregation.md) for Gateway configuration options.

### Related Documentation

- [Schema Validation](../modules/router/schema-validation.md) - JSON Schema validation in microservices
- [OpenAPI Aggregation](../modules/router/openapi-aggregation.md) - Gateway aggregation configuration
- [Gateway OpenAPI](../modules/gateway/openapi.md) - Implementation architecture