REST API OpenAPI spec (#612)

* OpenAPI spec in specs/api.  Checked lint with redoc.

specs/api/README.md

@@ -0,0 +1,84 @@
+# TrustGraph OpenAPI Specification
+
+This directory contains the modular OpenAPI 3.1 specification for the TrustGraph REST API Gateway.
+
+## Structure
+
+```
+specs/api/
+├── openapi.yaml              # Main entry point
+├── paths/                    # Endpoint definitions
+│   ├── config.yaml
+│   ├── flow.yaml
+│   ├── flow-services/        # Flow-hosted services
+│   └── import-export/
+├── components/
+│   ├── schemas/              # Request/response schemas
+│   │   ├── config/
+│   │   ├── flow/
+│   │   ├── ai-services/
+│   │   ├── common/
+│   │   └── errors/
+│   ├── parameters/           # Reusable parameters
+│   ├── responses/            # Reusable responses
+│   └── examples/             # Example payloads
+└── security/                 # Security schemes
+    └── bearerAuth.yaml
+```
+
+## Viewing the Spec
+
+### Swagger UI
+
+```bash
+# Install swagger-ui
+npm install -g swagger-ui-watcher
+
+# View in browser
+swagger-ui-watcher specs/api/openapi.yaml
+```
+
+### Redoc
+
+```bash
+# Install redoc-cli
+npm install -g redoc-cli
+
+# Generate static HTML
+redoc-cli bundle specs/api/openapi.yaml -o api-docs.html
+
+# View
+open api-docs.html
+```
+
+### Online Validators
+
+Upload `openapi.yaml` to:
+- https://editor.swagger.io/
+- https://redocly.com/redoc/
+
+## Validation
+
+```bash
+# Install openapi-spec-validator
+pip install openapi-spec-validator
+
+# Validate
+openapi-spec-validator specs/api/openapi.yaml
+```
+
+## Development
+
+When adding a new service:
+
+1. Create schema files in `components/schemas/{service}/`
+2. Create path file in `paths/` or `paths/flow-services/`
+3. Add examples if needed
+4. Reference from `openapi.yaml`
+5. Validate
+
+## References
+
+- [OpenAPI 3.1 Specification](https://spec.openapis.org/oas/v3.1.0)
+- [TrustGraph Tech Spec](../../docs/tech-specs/openapi-spec.md)
+- [API Services Summary](../../API_SERVICES_SUMMARY.md)