跳转至

CSAP Framework API Doc - Architecture

This document describes the architecture and design principles of CSAP Framework API Doc.

Table of Contents

Overview

CSAP Framework API Doc is a modular, extensible API documentation framework for Spring Boot applications. It follows a clean architecture approach with clear separation of concerns.

Key Characteristics

  • Zero Intrusion: Uses annotations without modifying existing code
  • Pluggable: Modular design with swappable components
  • Extensible: Multiple extension points for customization
  • Modern: Built with modern technologies (React 18, Spring Boot 3)

Architecture Diagram

┌─────────────────────────────────────────────────────────────────┐
│                      Spring Boot Application                     │
└─────────────────────────────────────────────────────────────────┘
                                │
                                ▼
┌─────────────────────────────────────────────────────────────────┐
│                    CSAP Apidoc Framework                         │
├─────────────────────────────────────────────────────────────────┤
│                                                                   │
│  ┌────────────────┐      ┌────────────────┐                     │
│  │   Annotation   │─────▶│    Scanner     │                     │
│  │    Processor   │      │    Engine      │                     │
│  └────────────────┘      └────────────────┘                     │
│          │                       │                               │
│          │                       ▼                               │
│          │              ┌────────────────┐                       │
│          └─────────────▶│   Parser &     │                       │
│                         │   Converter    │                       │
│                         └────────────────┘                       │
│                                 │                                │
│                                 ▼                                │
│                         ┌────────────────┐                       │
│                         │  Document      │                       │
│                         │  Generator     │                       │
│                         └────────────────┘                       │
│                                 │                                │
│         ┌───────────────────────┼───────────────────────┐       │
│         ▼                       ▼                       ▼        │
│  ┌─────────────┐       ┌─────────────┐       ┌─────────────┐   │
│  │   SQLite    │       │    YAML     │       │  Standard   │   │
│  │  Strategy   │       │  Strategy   │       │  Strategy   │   │
│  └─────────────┘       └─────────────┘       └─────────────┘   │
│         │                       │                       │        │
│         └───────────────────────┼───────────────────────┘       │
│                                 │                                │
│                                 ▼                                │
│                         ┌────────────────┐                       │
│                         │   REST API     │                       │
│                         └────────────────┘                       │
│                                 │                                │
└─────────────────────────────────┼────────────────────────────────┘
                                  │
                ┌─────────────────┼─────────────────┐
                ▼                 ▼                 ▼
        ┌──────────────┐  ┌──────────────┐  ┌──────────────┐
        │   DevTools   │  │   Web UI     │  │   Postman    │
        │  (React UI)  │  │  (React UI)  │  │  Converter   │
        └──────────────┘  └──────────────┘  └──────────────┘

Core Components

1. Annotation Processor

Location: csap-apidoc-annotation

Responsibilities: - Define documentation annotations - Provide annotation metadata - Support validation annotations

Key Classes: - @Api: Controller-level API documentation - @ApiOperation: Method-level API documentation - @ApiModel: Data model documentation - @ApiModelProperty: Field-level documentation - @ApiProperty: Parameter documentation

2. Scanner Engine

Location: csap-apidoc-core

Responsibilities: - Scan Spring MVC controllers - Detect API endpoints - Extract method signatures - Process annotations

Key Classes: - ApidocScanner: Main scanning logic - ControllerScanner: Controller detection - MethodScanner: Method analysis

3. Parser & Converter

Location: csap-apidoc-core

Responsibilities: - Parse Java types - Convert to documentation models - Handle nested structures - Process validation rules

Key Classes: - TypeParser: Java type parsing - ModelConverter: Model conversion - ValidationProcessor: JSR-303 integration

4. Document Generator

Location: csap-apidoc-core

Responsibilities: - Generate documentation data - Format output - Support multiple formats

Key Classes: - DocGenerator: Main generation logic - OpenAPIGenerator: OpenAPI format - PostmanConverterService: Postman format

5. Storage Strategy

Location: csap-apidoc-strategy

Responsibilities: - Persist documentation - Load documentation - Support multiple backends

Implementations: - SQLite: File-based database storage - YAML: Human-readable file storage - Standard: Simple JSON output

Interface:

public interface ApidocStorageStrategy {
    void save(CsapDocParentResponse docData);
    CsapDocParentResponse load();
}

6. REST API

Location: csap-apidoc-core

Responsibilities: - Expose documentation data - Handle API requests - Serve static resources

Endpoints: - GET /api/csap/doc: Get all documentation - GET /api/csap/doc/{id}: Get specific API doc - POST /api/csap/doc/save: Save configuration

7. Web UI

Location: csap-apidoc-ui, csap-apidoc-devtools

Responsibilities: - Display documentation - Provide online testing - Enable configuration management

Tech Stack: - React 18 - TypeScript 5.3 - Ant Design 5 - Zustand (state management) - Axios (HTTP client)

Module Structure

csap-framework-apidoc/
├── csap-apidoc-annotation     # Annotation definitions
├── csap-apidoc-common         # Common utilities
├── csap-apidoc-core           # Core logic
│   ├── scanner/                         # Scanning logic
│   ├── parser/                          # Parsing logic
│   ├── generator/                       # Generation logic
│   └── service/                         # Service layer
├── csap-apidoc-boot           # Spring Boot integration
│   ├── csap-apidoc-boot-starter
│   └── csap-validation-boot-starter
├── csap-apidoc-strategy       # Storage strategies
│   ├── csap-apidoc-sqlite
│   ├── csap-apidoc-yaml
│   └── csap-apidoc-standard
├── csap-apidoc-devtools       # DevTools UI
├── csap-apidoc-ui            # Web UI
└── csap-validation-core       # Validation integration

Data Flow

1. Initialization Flow

Application Startup
    │
    ▼
RunApplicationListener
    │
    ▼
Scan Controllers (base-package)
    │
    ▼
Process Annotations
    │
    ▼
Parse Types & Models
    │
    ▼
Generate Documentation
    │
    ▼
Save to Storage (Strategy)
    │
    ▼
Serve REST API

2. Request Flow

Browser Request
    │
    ▼
REST Controller
    │
    ▼
Load from Storage
    │
    ▼
Format Response
    │
    ▼
Return JSON
    │
    ▼
React UI Renders

3. Configuration Flow

User Edits in UI
    │
    ▼
POST to REST API
    │
    ▼
Validate Input
    │
    ▼
Update Model
    │
    ▼
Save to Storage
    │
    ▼
Broadcast Update (WebSocket)
    │
    ▼
UI Refreshes

Storage Strategies

Strategy Pattern Implementation

public interface ApidocStorageStrategy {
    void save(CsapDocParentResponse docData);
    CsapDocParentResponse load();
}

// SQLite Implementation
@Component
@ConditionalOnProperty(name = "csap.apidoc.storage-strategy", havingValue = "sqlite")
public class SqliteStorageStrategy implements ApidocStorageStrategy {
    // Implementation
}

// YAML Implementation
@Component
@ConditionalOnProperty(name = "csap.apidoc.storage-strategy", havingValue = "yaml")
public class YamlStorageStrategy implements ApidocStorageStrategy {
    // Implementation
}

Comparison

Strategy Pros Cons Use Case
SQLite Fast, indexed, persistent Binary format Production, performance-critical
YAML Human-readable, version control Slower parsing Development, documentation
Standard Simple, no dependencies No persistence Testing, debugging

Extension Points

1. Custom Storage Strategy

Implement ApidocStorageStrategy interface:

@Component
public class RedisStorageStrategy implements ApidocStorageStrategy {
    @Autowired
    private RedisTemplate<String, Object> redisTemplate;

    @Override
    public void save(CsapDocParentResponse docData) {
        redisTemplate.opsForValue().set("apidoc", docData);
    }

    @Override
    public CsapDocParentResponse load() {
        return (CsapDocParentResponse) redisTemplate.opsForValue().get("apidoc");
    }
}

2. Custom Annotation Processor

Extend annotation processing:

@Component
public class CustomAnnotationProcessor {

    @EventListener(ApplicationStartedEvent.class)
    public void processCustomAnnotations() {
        // Custom processing logic
    }
}

3. Custom Export Format

Implement custom exporters:

@Service
public class CustomExportService {

    public String exportToCustomFormat(CsapDocParentResponse apiDoc) {
        // Custom export logic
        return customFormatString;
    }
}

4. Custom UI Components

Extend React components:

// Custom field renderer
export const CustomFieldRenderer: React.FC<FieldProps> = ({ field }) => {
  return (
    <div className="custom-field">
      {/* Custom rendering logic */}
    </div>
  );
};

Design Principles

1. Separation of Concerns

Each module has a single, well-defined responsibility: - Annotation: Define metadata - Core: Process and generate - Storage: Persist data - UI: Display and interact

2. Open/Closed Principle

Open for extension, closed for modification: - Strategy pattern for storage - Plugin system for exporters - Component-based UI

3. Dependency Inversion

Depend on abstractions, not concretions: - ApidocStorageStrategy interface - Spring dependency injection - Loose coupling between modules

4. Single Responsibility

Each class has one reason to change: - Scanner only scans - Parser only parses - Generator only generates

5. Don't Repeat Yourself (DRY)

Common functionality extracted to: - csap-apidoc-common - Shared utilities - Reusable components

Performance Considerations

1. Lazy Initialization

  • Documentation generated on first access
  • Asynchronous processing
  • Caching strategies

2. Efficient Scanning

  • Package-based filtering
  • Incremental scanning
  • Annotation indexing

3. Optimized Storage

  • Indexed database queries
  • Compressed YAML
  • Connection pooling

4. Frontend Optimization

  • Code splitting
  • Lazy loading
  • Virtual scrolling for large lists
  • Memoization

Security Considerations

1. Input Validation

  • All user inputs validated
  • Sanitization before storage
  • XSS prevention

2. Access Control

  • Optional authentication
  • IP whitelisting
  • Role-based permissions (planned)

3. Data Protection

  • Sensitive field masking
  • Secure storage
  • HTTPS enforcement

Future Architecture Evolution

Phase 1: Enhanced Core (v2.0)

  • Improved caching
  • Better performance
  • Enhanced validation

Phase 2: Collaboration (v3.0)

  • WebSocket real-time sync
  • Version control
  • Team features

Phase 3: Enterprise (v4.0)

  • Microservices support
  • Distributed architecture
  • Advanced monitoring

For more details on specific modules, see: - README.md - General overview - CONTRIBUTING.md - Development guidelines - Product Roadmap - Future plans