/devkit.java.generate-docs

allowed-tools: Read, Write, Edit, Bash, Grep, Glob
argument-hint: "[project-path] [doc-types] [output-format]"
description: Generates comprehensive Java project documentation including API docs, architecture diagrams, and Javadoc. Use when creating or updating project documentation.
model: inherit

Generate Java Project Documentation

Overview

Generates comprehensive Java project documentation including API docs, architecture diagrams, and Javadoc. Use when creating or updating project documentation.

You are a Java documentation expert specializing in creating comprehensive, maintainable documentation for Java Spring Boot projects. Generate professional documentation following Java and Spring ecosystem standards.

Usage

/devkit.java.generate-docs $ARGUMENTS

Arguments

| Argument | Description | |--------------|------------------------------------------| | `$ARGUMENTS` | Combined arguments passed to the command |

Execution Instructions

**Agent Selection**: To execute this task, use the following agent with fallback:

• Primary: `developer-kit-java:java-documentation-specialist`
• If not available: Use `developer-kit-java:java-documentation-specialist` or fallback to `general-purpose` agent

Current Project Context

• **Project Root**: !`pwd`
• **Build System**: Detected from `pom.xml` (Maven) or `build.gradle*` (Gradle)
• **Git Branch**: !`git branch --show-current`
• **Java Version**: Extracted from build configuration
• **Spring Boot Version**: Extracted from dependencies

Configuration

**Arguments received**: `$ARGUMENTS`

**Default project path**: Current directory **Available doc types**:

• `api` - REST API documentation with OpenAPI/Swagger
• `architecture` - System architecture and design documentation
• `javadoc` - Comprehensive Javadoc generation
• `readme` - Project README and setup guides
• `full` - Complete documentation suite (default)

**Output formats**:

• `html` - HTML documentation site
• `markdown` - Markdown files
• `asciidoc` - AsciiDoc format
• `confluence` - Confluence-compatible format

Phase 1: Project Analysis

1.1 Detect Project Structure

Analyze the project to understand:

# Detect build system
if [ -f "pom.xml" ]; then
    echo "Maven project detected"
    MVN_VERSION=$(mvn help:evaluate -Dexpression=project.version -q -DforceStdout 2>/dev/null)
    JAVA_VERSION=$(mvn help:evaluate -Dexpression=maven.compiler.source -q -DforceStdout 2>/dev/null)
elif [ -f "build.gradle" ] || [ -f "build.gradle.kts" ]; then
    echo "Gradle project detected"
    ./gradlew properties --quiet | grep "version:"
    ./gradlew properties --quiet | grep "sourceCompatibility"
fi

1.2 Identify Technology Stack

Search for key dependencies and annotations:

• **Spring Boot**: `@SpringBootApplication`, `spring-boot-starter-*`
• **Spring Framework**: `@RestController`, `@Service`, `@Repository`
• **Database**: JPA entities, `@Entity`, Spring Data repositories
• **Security**: Spring Security configuration, JWT
• **Testing**: JUnit 5, Mockito, Testcontainers
• **Documentation**: Swagger/OpenAPI annotations
• **Build Tools**: Maven plugins, Gradle plugins

1.3 Package Structure Analysis

src/main/java/
├── config/           # Configuration classes
├── controller/       # REST controllers
├── service/          # Business logic services
├── repository/       # Data access layer
├── domain/           # Domain entities
├── dto/              # Data transfer objects
├── exception/        # Custom exceptions
└── util/             # Utility classes

Phase 2: API Documentation Generation

2.1 OpenAPI/Swagger Configuration

**SpringDoc OpenAPI Setup**:

@Configuration
@OpenAPIDefinition(
        info = @Info(
                title = "API Documentation",
                version = "1.0.0",
                description = "Spring Boot REST API documentation",
                contact = @Contact(
                        name = "Development Team",
                        email = "dev@example.com"
                ),
                license = @License(
                        name = "Apache 2.0",
                        url = "https://www.apache.org/licenses/LICENSE-2.0"
                )
        ),
        servers = {
                @Server(url = "/", description = "Default server"),
                @Server(url = "https://api.example.com", description = "Production server")
        }
)
public class OpenApiConfig {

    @Bean
    public GroupedOpenApi publicApi() {
        return GroupedOpenApi.builder()
                .group("public")
                .pathsToMatch("/api/public/**")
                .build();
    }

    @Bean
    public GroupedOpenApi adminApi() {
        return GroupedOpenApi.builder()
                .group("admin")
                .pathsToMatch("/api/admin/**")
                .addOpenApiMethodFilter(method -> method.isAnnotationPresent(PreAuthorize.class))
                .build();
    }
}

2.2 Enhanced Controller Documentation

@RestController
@RequestMapping("/api/v1/users")
@Tag(name = "User Management", description = "User CRUD operations")
@SecurityRequirement(name = "bearerAuth")
public class UserController {

    @GetMapping
    @Operation(
            summary = "Get all users",
            description = "Retrieve a paginated list of users with optional filtering",
            responses = {
                    @ApiResponse(
                            responseCode = "200",
                            description = "Users retrieved successfully",
                            content = @Content(
                                    mediaType = "application/json",
                                    schema = @Schema(implementation = PaginatedUserResponse.class)
                            )
                    ),
                    @ApiResponse(
                            responseCode = "401",
                            description = "Unauth