中文 | English

Marginalia

Generate API Documentation from Source Code Comments for Spring Boot

Extract API docs directly from Javadoc and source comments — no annotation invasion required.
Includes a Postman-style Web UI for browsing documentation and debugging APIs.

   

---

---

Features

• Zero Annotation Invasion — No extra annotations needed; extracts docs from Javadoc, line comments, and Swagger annotations
• Priority Chain — Javadoc > Line Comments > Swagger Annotations > Method Signature
• Built-in Web UI — Postman-style interface with Document mode and Debug mode
• API Debugger — Built-in HTTP client for sending requests, custom headers/params, response viewing, and SSE support
• Entity Auto-Discovery — Automatically discovers entity classes from request/response body types with full field structure
• Field-Level Merge — User edits are preserved across re-scans
• Directory Persistence — Documentation stored as files; all edits survive restarts
• Out of the Box — Spring Boot Starter; just add the dependency

Quick Start

1. Add Dependency

<dependency>
    <groupId>ink.icoding</groupId>
    <artifactId>marginalia-spring-boot-starter</artifactId>
    <version>1.1.0</version><!-- version -->
</dependency>

2. Start Application

Start your Spring Boot application, then visit http://localhost:8080/marginalia to view the documentation.

3. Configure (Optional)

Add to application.yaml:

marginalia:
  enabled: true                    # Enable/disable, default: true
  prefix: /marginalia             # Web UI path, default: /marginalia
  base-package: com.example       # Base package to scan, empty = scan all
  source-dirs:                    # Source directories, empty = auto-detect
    - src/main/java
  data-dir: ./marginalia-data     # Documentation data directory
  auto-scan: true                 # Auto-scan on startup
  debugger-enabled: true          # Enable debugger feature
  title: API Documentation        # Custom title

How It Works

1. Startup Scan — Scans all Java files in the project's source directories at application startup
2. Parse Controllers — Uses JavaParser to parse @Controller / @RestController classes
3. Extract Docs — Extracts API descriptions from Javadoc, comments, and annotations by priority
4. Discover Entities — Automatically discovers and parses entity classes from request/response types (supports nested generics)
5. Merge & Persist — Merges with existing data; user-modified fields take priority
6. Serve UI — Displays documentation through a built-in web interface with browse and debug capabilities

Documentation Source Priority

Source	Example	Priority
Javadoc	/** Get user info */	Highest
Line Comment	// Get user info	High
Swagger Annotation	@ApiOperation("Get user info")	Medium
Method Signature	getUserInfo()	Lowest

Web UI

Document Mode

• API path, HTTP method, and description
• Path variables, query parameters, header parameters
• Request body (with entity field-level display)
• Response body (with entity field-level display + JSON example)
• Clickable entity names that navigate to entity detail pages

Debug Mode

• Select HTTP method and enter URL
• Custom Params, Headers, and Body
• Send requests and view responses
• SSE (Server-Sent Events) support
• Edits auto-saved; persist across page refreshes

Project Structure

marginalia/
├── marginalia-core                    # Core library
│   ├── model/                         # Data models
│   ├── parser/                        # Source parser (JavaParser)
│   ├── scanner/                       # Source scanner
│   ├── persistence/                   # Directory-based persistence
│   └── service/                       # Core service
└── marginalia-spring-boot-starter     # Spring Boot Starter
    ├── autoconfigure/                 # Auto-configuration
    └── resources/static/marginalia/   # Web UI (single-file SPA)

License

GPLv3