Muonica

Muonica is an extensible API documentation library for Spring Boot. It scans Spring MVC applications into a framework-independent model, combines generated API metadata with Markdown written for humans, and exposes both an interactive documentation UI and an OpenAPI 3.1.1 document.

Muonica's Java model is the source of truth. Spring integration, the UI, and OpenAPI are adapters around that model.

Features

• Automatic discovery of Spring MVC endpoints, parameters, request and response schemas, validation constraints, multipart parts, pageable parameters, and security metadata.
• Explicit annotations for project information, groups, operations, responses, and security schemes.
• Markdown documentation packaged with the application JAR.
• Documentation inheritance from project to group to endpoint.
• Generated technical sections for requests, responses, parameters, and security requirements.
• Notices and Mermaid diagrams through lightweight Markdown directives.
• A framework-free UI served directly by the Spring integration module.
• OpenAPI 3.1.1 export from the neutral Muonica model.
• Muonica-native metadata for hidden endpoints, badges, descriptions, examples, defaults, response headers, and project servers.
• Strict documentation validation by default, with optional warnings for non-strict environments.

Modules

• muonica-core — framework-independent annotations and documentation model.
• muonica-spring — Spring MVC scanner, documentation composition, auto-configuration, and web endpoints.
• muonica-openapi — OpenAPI 3.1.1 export adapter.
• muonica-ui — bundled Muonica Pages frontend and static resources.
• muonica-demo — executable Spring Boot application used as a reference implementation and integration test fixture.

Getting Started (for Developers)

Prerequisites

• JDK 17 or newer
• A terminal, or IntelliJ IDEA with Gradle support

The repository includes a Gradle wrapper, so a separate Gradle installation is not required.

Build and test

From the repository root:

./gradlew test

To build every module:

./gradlew build

To test only the reusable libraries and collect their JARs in one directory, run:

./gradlew buildLibraries

The task runs checks for muonica-core, muonica-openapi, muonica-ui, and muonica-spring, then copies their JARs to build/libs at the repository root. It does not build the demo application.

Run the demo application

Start the reference Spring Boot application with:

./gradlew :muonica-demo:bootRun

Once the application starts, open http://localhost:8080/docs to view the generated documentation.

The demo also exposes the underlying representations:

Endpoint	Description
/docs	Redirects to the documentation UI.
/docs/api	Returns the Muonica JSON model.
/docs/openapi.json	Returns the generated OpenAPI 3.1.1 document.

Configure another base path when needed:

muonica:
  web:
    path: /reference

The UI, JSON model, OpenAPI document, and bundled assets are then served below /reference. Leading and trailing slashes are normalized, so reference/ is equivalent to /reference and / serves the UI at the application root.

Add Muonica to an Application

Add the Spring integration module to the application that should expose documentation. In this multi-module build, the demo uses:

dependencies {
    implementation(project(":muonica-spring"))
}

Muonica is auto-configured for servlet-based Spring Boot applications. Add project-level metadata in a configuration class:

@Configuration
class ApiDocumentationConfig {
    @Bean
    MuonicaDocumentation muonicaDocumentation() {
        return MuonicaDocumentation.builder()
                .project("Example API", "1.0.0", "An API documented with Muonica.")
                .pageFromFile("Overview", "classpath:/muonica/index.md")
                .build();
    }
}

Annotate controllers and handler methods when generated metadata needs additional context:

@RestController
@RequestMapping("/users")
@MuonicaGroup(name = "Users", description = "Manage users.")
@MuonicaDocumentation(file = "classpath:/muonica/users/index.md")
class UserController {
    @GetMapping("/{id}")
    @MuonicaOperation(summary = "Get a user", description = "Returns a user by identifier.")
    @MuonicaDocumentation(file = "classpath:/muonica/users/get-user.md")
    UserResponse getUser(@PathVariable long id) {
        // ...
    }
}

Use @MuonicaHidden to omit a controller or handler from generated documentation without changing Spring MVC routing. Use repeatable @MuonicaBadge("ADMIN") for endpoint labels. The UI gives ADMIN, BETA, DEPRECATED, and INTERNAL their own Muonica-style color treatments; custom labels remain supported with a neutral treatment. @MuonicaDescription, @MuonicaExample, and @MuonicaDefault apply to DTO types, fields, record components, and parameters.

Security requirements are OR-of-AND groups: one @MuonicaSecurityRequirement({"bearerAuth", "apiKey"}) requires both schemes, while repeated annotations express alternatives. Declare project servers and security schemes through the MuonicaDocumentation bean. @MuonicaResponse supports typed @MuonicaResponseHeader declarations. Badges are also available in OpenAPI as x-muonica-badges.

Write Markdown Documentation

Markdown resources are loaded from the classpath and composed with the generated API reference. A resource can contain regular Markdown and Muonica directives:

# Get a user

Returns the user profile for the requested identifier.

:::notice warning
The endpoint requires an authenticated request.
:::

:::slot parameters
:::

:::slot responses
:::

Supported directives include:

• :::notice info, :::notice warning, and :::notice danger
• :::diagram mermaid
• :::slot security, :::slot request, :::slot responses, and :::slot parameters

Documentation is resolved and cached during application startup. If a source is invalid, Muonica fails fast by default. To keep the application running and expose diagnostics in the JSON model instead, configure:

muonica:
  documentation:
    strict: false

Architecture

Spring MVC application
        ↓
   muonica-spring
        ↓
    muonica-core
     ↙       ↘
  Muonica UI  OpenAPI 3.1.1

The core model remains independent of Spring and OpenAPI. This keeps the scanner, UI, and exporters replaceable without changing the documentation model itself.

Contributing

Contributions and improvements are welcome. Before opening a change:

1. Run ./gradlew test.
2. Keep new functionality covered by unit or integration tests where practical.
3. Follow the existing Java and Kotlin Gradle build conventions.
4. Use a Conventional Commit message, for example feat(spring): add custom documentation endpoint support.

License

Muonica's code is licensed under the Apache License, Version 2.0. The project name and branding are covered separately by the trademark and branding policy.