Skip to content

openapi-implementation.md

Latest commit

 

History

History
237 lines (177 loc) · 8.65 KB

openapi-implementation.md

File metadata and controls

237 lines (177 loc) · 8.65 KB
Raw

OpenAPI Implementation

Overview

This document summarizes the implementation of OpenAPI/Swagger documentation for the Scopeon Server API, enabling frontend developers to have comprehensive API documentation and contract specifications.

⚠️ IMPORTANT: This document describes the legacy OpenAPI implementation. A new Route-First OpenAPI Architecture has been implemented to solve synchronization issues. See route-first-openapi-architecture.md for the new approach.

Legacy Implementation Details (Deprecated)

1. Core OpenAPI Configuration

File: src/web/api/openapi.rs (Legacy)

  • utoipa crate integration for automatic OpenAPI generation
  • Comprehensive API documentation structure with proper metadata
  • Security schemes for both session-based (frontend) and API key (desktop agents) authentication
  • Response templates for standardized error handling
  • Pagination support for list endpoints

2. Endpoint Documentation

Health Endpoints

File: src/web/api/handlers/health.rs

All health check endpoints now include complete OpenAPI annotations:

  • GET /health - Basic health check
  • GET /health/detailed - Detailed service status
  • GET /health/ready - Kubernetes readiness probe
  • GET /health/live - Kubernetes liveness probe

Authentication Endpoints

File: src/web/auth.rs

REST API authentication endpoints with full documentation:

  • POST /auth/api/login - User login with credentials
  • POST /auth/api/logout - User logout
  • GET /auth/api/me - Current user information

3. Schema Documentation

Domain Models

Files: src/domain/*/models.rs

Updated core domain models with ToSchema annotations:

  • User Management: User, UserRole, UserStatus
  • Health Models: HealthResponse, ServiceStatus, ServiceHealth
  • API Models: ApiResponse<T>, ApiError, PaginationInfo

Request/Response Models

Files: src/web/auth.rs, src/web/api/models.rs

Documented data transfer objects:

  • Authentication: LoginForm, LoginResponse, UserInfo
  • Generic API responses with proper typing and validation schemas

4. Server Integration

Routing Configuration

File: src/web/routing.rs

Added OpenAPI endpoints to the server with HTTPS support:

  • Swagger UI: https://localhost:8080/swagger-ui/ (default HTTPS) or http://localhost:8080/swagger-ui/ (when TLS disabled)
  • OpenAPI JSON: https://localhost:8080/api-docs/openapi.json (default HTTPS) or http://localhost:8080/api-docs/openapi.json (when TLS disabled)

HTTPS Configuration

File: src/infrastructure/tls.rs

TLS/HTTPS support with security features:

  • Self-signed certificate generation for development
  • Custom certificate loading for production
  • Secure session cookies with HttpOnly, SameSite=Lax, Secure flags
  • CORS configuration compliant with credential security requirements

Startup Logging

Enhanced server startup logs to include documentation URLs, authentication information, and TLS status.

Available Documentation

1. Interactive Swagger UI

https://localhost:8080/swagger-ui/  (Default - HTTPS with TLS enabled)
http://localhost:8080/swagger-ui/   (Fallback - HTTP when ENABLE_TLS=false)

Features:

  • Interactive API exploration
  • Request/response testing
  • Schema visualization
  • Authentication testing interface
  • Secure HTTPS access with session cookies

2. OpenAPI Specification

https://localhost:8080/api-docs/openapi.json  (Default HTTPS)
http://localhost:8080/api-docs/openapi.json   (HTTP when TLS disabled)

Features:

  • Machine-readable API contract
  • Complete schema definitions
  • Authentication schemes
  • Endpoint specifications

Authentication Documentation

Frontend Authentication (Session-based)

  • Cookie-based session management
  • Login/logout endpoints
  • User information retrieval
  • Role-based authorization

Desktop Agent Authentication (API Key)

  • Header-based API key authentication
  • WebSocket connection support
  • Programmatic access patterns

Security Configuration

HTTPS/TLS Support

  • Development: Self-signed certificates generated automatically
  • Production: Custom certificate loading with proper validation
  • Session Security: HttpOnly, SameSite=Lax, Secure cookies for HTTPS
  • CORS Security: Credential-safe CORS configuration with specific origins

Supported Auth Schemes

  1. session_auth: Cookie-based authentication for Angular frontend
  2. api_key: Header-based authentication for desktop agents

CORS Configuration

  • Credentials Enabled: Supports session cookies for frontend authentication
  • Allowed Origins: Specific origins (localhost:4200) instead of wildcard for security
  • Allowed Methods: GET, POST, PUT, DELETE, PATCH, OPTIONS
  • Allowed Headers: Authorization, Content-Type, X-Requested-With, Accept, Origin, X-CSRF-Token

Authorization Levels

  • HostOwner: Basic host management
  • SecurityAnalyst: Vulnerability analysis
  • SecurityManager: Security oversight
  • SystemAdmin: Full system access

Future Endpoint Integration

The OpenAPI configuration is prepared for future endpoint documentation:

Planned Endpoints

  • User Management: CRUD operations for user management
  • Host Management: Host registration, status, and monitoring
  • Vulnerability Management: CVE analysis and reporting
  • Software Inventory: Software detection and management
  • Report Generation: Security report creation and export

Integration Process

  1. Add endpoint handler with #[utoipa::path] annotations
  2. Include handler in ApiDoc paths section
  3. Add response/request models to schemas section
  4. Update routing configuration

Development Benefits

For Frontend Developers

  • Clear API contracts and specifications
  • Interactive testing environment
  • Automatic client library generation support
  • Real-time API exploration

For Backend Developers

  • Automatic documentation generation
  • Schema validation enforcement
  • Standardized response formats
  • Development-time API contract verification

For QA/Testing

  • Interactive API testing interface
  • Clear endpoint specifications
  • Authentication flow documentation
  • Response format validation

Usage Examples

Testing Authentication

# Login request (HTTPS when enabled)
curl -X POST https://localhost:8080/auth/api/login \
  -H "Content-Type: application/json" \
  -d '{"username": "admin", "password": "admin_password"}' \
  --insecure  # Only for self-signed certificates in development

# Get current user info
curl https://localhost:8080/auth/api/me \
  -H "Cookie: session=<session_token>" \
  --insecure  # Only for self-signed certificates in development

Health Check

# Basic health check (HTTPS when enabled)
curl https://localhost:8080/health --insecure

# Detailed health status (adjust protocol based on ENABLE_TLS)
curl https://localhost:8080/health --insecure

Conclusion

The OpenAPI documentation system is now fully operational and provides:

✅ Complete API Documentation - All current endpoints documented with schemas ✅ Interactive Testing - Swagger UI for development and testing
✅ HTTPS Security - TLS encryption with secure session management ✅ CORS Compliance - Credential-safe CORS configuration ✅ Authentication Integration - Both session and API key auth documented ✅ Extensible Architecture - Ready for future endpoint additions ✅ Developer Experience - Clear contracts for frontend development ✅ Standardized Responses - Consistent API response formats

This implementation enables the frontend team to begin development with clear API specifications while the backend continues to evolve, supporting the co-development strategy outlined in the project architecture.

New Route-First OpenAPI Architecture

⚠️ Migration in Progress: The above implementation is being replaced with a new Route-First OpenAPI Architecture that solves the synchronization problem between routes and documentation.

Key Improvements

  • Co-located Documentation: Routes and OpenAPI docs are defined together
  • Automatic Synchronization: No more manual maintenance of two separate systems
  • Compile-time Safety: Impossible to have routes without documentation
  • Modular Organization: Each API domain is self-contained

Access Points

  • Legacy Documentation: /swagger-ui/ (existing endpoints)
  • New Architecture Demo: /swagger-ui-modular/ (migrated modules)
  • Legacy JSON: /api-docs/openapi.json
  • New JSON: /api-docs/openapi-modular.json

See route-first-openapi-architecture.md for complete details on the new architecture and migration strategy.