cc69d332e3
Some checks failed
Docs CI / lint-and-preview (push) Has been cancelled
- Implemented comprehensive unit tests for RabbitMqTransportServer, covering constructor, disposal, connection management, event handlers, and exception handling. - Added configuration tests for RabbitMqTransportServer to validate SSL, durable queues, auto-recovery, and custom virtual host options. - Created unit tests for UdpFrameProtocol, including frame parsing and serialization, header size validation, and round-trip data preservation. - Developed tests for UdpTransportClient, focusing on connection handling, event subscriptions, and exception scenarios. - Established tests for UdpTransportServer, ensuring proper start/stop behavior, connection state management, and event handling. - Included tests for UdpTransportOptions to verify default values and modification capabilities. - Enhanced service registration tests for Udp transport services in the dependency injection container.
117 lines
3.1 KiB
Markdown
117 lines
3.1 KiB
Markdown
# 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
|