Generate Java Project Documentation

/devkit.java.generate-docs $ARGUMENTS

# 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

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

@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();
    }
}

@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 = "Unauthorized",
                            content = @Content(
                                    mediaType = "application/json",
                                    schema = @Schema(implementation = ErrorResponse.class)
                            )
                    )
            }
    )
    public ResponseEntity<PaginatedResponse<UserDto>> getUsers(
            @Parameter(description = "Page number (0-based)", example = "0")
            @RequestParam(defaultValue = "0") int page,

            @Parameter(description = "Page size", example = "20")
            @RequestParam(defaultValue = "20") int size,

            @Parameter(description = "Sort field", example = "name")
            @RequestParam(defaultValue = "name") String sort,

            @Parameter(description = "Search term for name/email")
            @RequestParam(required = false) String search
    ) {
        // Implementation
    }
}

@Schema(description = "User data transfer object")
public record UserDto(
        @Schema(description = "Unique user identifier", example = "123e4567-e89b-12d3-a456-426614174000", accessMode = Schema.AccessMode.READ_ONLY)
        UUID id,

        @Schema(description = "User's full name", example = "John Doe", minLength = 2, maxLength = 100)
        @NotBlank(message = "Name is required")
        String name,

        @Schema(description = "User email address", example = "john.doe@example.com", format = "email")
        @NotBlank(message = "Email is required")
        @Email(message = "Invalid email format")
        String email,

        @Schema(description = "Account creation timestamp", example = "2024-01-15T10:30:00Z", accessMode = Schema.AccessMode.READ_ONLY)
        @JsonFormat(pattern = "yyyy-MM-dd'T'HH:mm:ss'Z'")
        LocalDateTime createdAt
) {
    @JsonCreator
    public UserDto {
        Objects.requireNonNull(id, "ID cannot be null");
        Objects.requireNonNull(name, "Name cannot be null");
        Objects.requireNonNull(email, "Email cannot be null");
    }
}

## System Architecture

```mermaid
graph TB
    subgraph "Client Layer"
        WebApp[Web Application]
        MobileApp[Mobile App]
        ExternalSystem[External Systems]
    end

    subgraph "API Gateway"
        Gateway[Spring Cloud Gateway]
        Auth[Authentication Service]
        RateLimit[Rate Limiting]
    end

    subgraph "Application Layer"
        UserController[User API]
        OrderController[Order API]
        ProductController[Product API]
    end

    subgraph "Service Layer"
        UserService[User Service]
        OrderService[Order Service]
        ProductService[Product Service]
        NotificationService[Notification Service]
    end

    subgraph "Data Layer"
        PostgreSQL[(PostgreSQL)]
        Redis[(Redis Cache)]
        Elasticsearch[(Elasticsearch)]
        FileStorage[File Storage]
    end

    subgraph "External Services"
        PaymentGateway[Payment Gateway]
        EmailService[Email Service]
        SMSService[SMS Service]
    end

    WebApp --> Gateway
    MobileApp --> Gateway
    ExternalSystem --> Gateway

    Gateway --> Auth
    Gateway --> RateLimit
    Gateway --> UserController
    Gateway --> OrderController
    Gateway --> ProductController

    UserController --> UserService
    OrderController --> OrderService
    ProductController --> ProductService

    UserService --> PostgreSQL
    UserService --> Redis
    OrderService --> PostgreSQL
    OrderService --> NotificationService
    ProductService --> Elasticsearch

    NotificationService --> EmailService
    NotificationService --> SMSService
    OrderService --> PaymentGateway

## Component Architecture

### Domain Layer

- **Purpose**: Core business logic and domain models
- **Technologies**: Plain Java objects, no Spring dependencies
- **Responsibilities**: Business rules, domain services, repositories interfaces

### Application Layer

- **Purpose**: Use cases and application services
- **Technologies**: Spring Boot, @Service, @Transactional
- **Responsibilities**: Orchestrate domain objects, handle transactions

### Infrastructure Layer

- **Purpose**: External concerns and implementations
- **Technologies**: Spring Data JPA, external APIs, file systems
- **Responsibilities**: Database access, external integrations, caching

### Presentation Layer

- **Purpose**: API endpoints and data transformation
- **Technologies**: Spring Web, DTOs, validation
- **Responsibilities**: HTTP handling, request/response mapping

## Data Flow Patterns

### User Registration Flow

```mermaid
sequenceDiagram
    participant Client
    participant API as REST Controller
    participant Service as User Service
    participant Repo as User Repository
    participant Cache as Redis Cache
    participant Email as Email Service

    Client->>API: POST /api/users
    API->>API: Validate @Valid CreateUserRequest
    API->>Service: userService.createUser(request)
    Service->>Repo: userRepository.existsByEmail(email)
    Repo-->>Service: false
    Service->>Service: passwordEncoder.encode(password)
    Service->>Repo: userRepository.save(user)
    Repo-->>Service: User entity
    Service->>Cache: cache.evict("users:*")
    Service->>Email: emailService.sendWelcomeEmail(user)
    Service-->>API: UserDto
    API-->>Client: 201 Created + UserDto

sequenceDiagram
    participant Client
    participant API as Order Controller
    participant Service as Order Service
    participant Payment as Payment Gateway
    participant Inventory as Inventory Service
    participant Notification as Notification Service
    Client ->> API: POST /api/orders
    API ->> Service: orderService.createOrder(request)
    Service ->> Inventory: inventoryService.reserveItems(items)
    Inventory -->> Service: Reservation confirmed
    Service ->> Payment: paymentGateway.processPayment(paymentDetails)
    Payment -->> Service: Payment successful
    Service ->> Service: orderRepository.save(order)
    Service ->> Notification: notificationService.sendOrderConfirmation(order)
    Service -->> API: OrderDto
    API -->> Client: 201 Created + OrderDto

/**
 * Service for managing user accounts and authentication.
 *
 * <p>This service provides business logic for user registration, authentication,
 * profile management, and security operations. It follows Spring Boot best
 * practices and implements proper error handling and logging.</p>
 *
 * <h3>Key Features:</h3>
 * <ul>
 *   <li>User registration with email verification</li>
 *   <li>Password hashing and validation</li>
 *   <li>JWT token generation and validation</li>
 *   <li>User profile management</li>
 * </ul>
 *
 * @author Development Team
 * @version 1.0.0
 * @since 1.0.0
 *
 * @see UserRepository for data access operations
 * @see PasswordEncoder for password hashing
 * @see JwtTokenProvider for JWT operations
 */
@Service
@Transactional
@RequiredArgsConstructor
@Slf4j
public class UserService {

    private final UserRepository userRepository;
    private final PasswordEncoder passwordEncoder;
    private final JwtTokenProvider jwtTokenProvider;
    private final ApplicationEventPublisher eventPublisher;

    /**
     * Creates a new user account with the provided registration data.
     *
     * <p>This method performs the following operations:</p>
     * <ol>
     *   <li>Validates the registration request</li>
     *   <li>Checks for duplicate email addresses</li>
     *   <li>Hashes the user's password</li>
     *   <li>Saves the user to the database</li>
     *   <li>Publishes a user registration event</li>
     * </ol>
     *
     * @param request the user registration data, must not be {@code null}
     * @return the created user information as a DTO
     * @throws UserAlreadyExistsException if a user with the same email already exists
     * @throws ValidationException if the request data is invalid
     * @throws IllegalArgumentException if {@code request} is {@code null}
     *
     * @see UserRegistrationRequest for request structure
     * @see UserDto for response structure
     * @see UserRegisteredEvent for the published event
     */
    @Transactional
    public UserDto createUser(@Valid UserRegistrationRequest request) {
        log.info("Creating user with email: {}", request.email());

        validateRegistrationRequest(request);

        if (userRepository.existsByEmail(request.email())) {
            throw new UserAlreadyExistsException(request.email());
        }

        var user = buildUserFromRequest(request);
        var savedUser = userRepository.save(user);

        eventPublisher.publishEvent(new UserRegisteredEvent(savedUser));

        log.info("User created successfully with ID: {}", savedUser.getId());
        return UserDto.fromEntity(savedUser);
    }
}

<plugin>
    <groupId>org.apache.maven.plugins</groupId>
    <artifactId>maven-javadoc-plugin</artifactId>
    <version>3.6.0</version>
    <configuration>
        <source>17</source>
        <target>17</target>
        <encoding>UTF-8</encoding>
        <charset>UTF-8</charset>
        <docencoding>UTF-8</docencoding>
        <doclint>all</doclint>
        <breakiterator>true</breakiterator>
        <show>private</show>
        <nodeprecated>false</nodeprecated>
        <sourcepath>
            ${project.build.sourceDirectory}
        </sourcepath>
        <subpackages>
            com.example.controller
            com.example.service
            com.example.repository
            com.example.domain
            com.example.dto
            com.example.config
        </subpackages>
        <excludePackageNames>
            com.example.generated.*:com.example.util.internal.*
        </excludePackageNames>
        <links>
            <link>https://docs.spring.io/spring-framework/docs/current/javadoc-api/</link>
            <link>https://docs.spring.io/spring-boot/docs/current/api/</link>
            <link>https://jakarta.ee/specifications/platform/10/apidocs/</link>
            <link>https://javadoc.io/doc/org.junit.jupiter/junit-jupiter-api/</link>
        </links>
        <groups>
            <group>
                <title>Web Layer</title>
                <packages>com.example.controller:com.example.dto</packages>
            </group>
            <group>
                <title>Service Layer</title>
                <packages>com.example.service</packages>
            </group>
            <group>
                <title>Data Layer</title>
                <packages>com.example.repository:com.example.domain</packages>
            </group>
            <group>
                <title>Configuration</title>
                <packages>com.example.config</packages>
            </group>
        </groups>
        <tags>
            <tag>
                <name>since</name>
                <placement>a</placement>
                <head>Since:</head>
            </tag>
            <tag>
                <name>author</name>
                <placement>a</placement>
                <head>Author:</head>
            </tag>
        </tags>
    </configuration>
    <executions>
        <execution>
            <id>attach-javadocs</id>
            <goals>
                <goal>jar</goal>
            </goals>
        </execution>
        <execution>
            <id>aggregate</id>
            <goals>
                <goal>aggregate</goal>
            </goals>
            <phase>site</phase>
        </execution>
    </executions>
</plugin>

# Project Name

[![Build Status](https://img.shields.io/github/actions/workflow/status/username/project/ci.yml?branch=main)](https://github.com/username/project/actions)
[![Coverage](https://img.shields.io/codecov/c/github/username/project)](https://codecov.io/gh/username/project)
[![License](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](https://opensource.org/licenses/Apache-2.0)
[![Spring Boot](https://img.shields.io/badge/Spring%20Boot-3.2.0-brightgreen.svg)](https://spring.io/projects/spring-boot)

> Brief, compelling description of what your project does and its key benefits.

## 🚀 Features

- ✅ **Feature 1**: Description with key benefits
- ✅ **Feature 2**: Description with key benefits
- ✅ **Feature 3**: Description with key benefits
- 🔒 **Security**: Spring Security with JWT authentication
- 📊 **Monitoring**: Spring Boot Actuator with custom health checks
- 🧪 **Testing**: Comprehensive test suite with Testcontainers

## 📋 Prerequisites

- **Java 17+** (OpenJDK or Oracle JDK)
- **Maven 3.8+** or **Gradle 8.0+**
- **PostgreSQL 14+** (for production)
- **Redis 6+** (for caching, optional)

## 🛠 Quick Start

### Using Docker Compose (Recommended)

```bash
# Clone the repository
git clone https://github.com/username/project.git
cd project

# Start all services
docker-compose up -d

# Wait for services to be ready (approximately 30 seconds)
docker-compose logs -f

# Access the application
curl http://localhost:8080/actuator/health

# Clone and build
git clone https://github.com/username/project.git
cd project
./mvnw clean install

# Start PostgreSQL and Redis
docker-compose up -d postgres redis

# Run the application
./mvnw spring-boot:run

# Or run with specific profile
./mvnw spring-boot:run -Dspring-boot.run.profiles=dev

# Run all tests
./mvnw test

# Run tests with coverage
./mvnw test jacoco:report

# Run integration tests only
./mvnw test -Pintegration-tests

# Run specific test class
./mvnw test -Dtest=UserServiceTest

# View metrics
curl http://localhost:8080/actuator/prometheus

# Custom metrics
curl http://localhost:8080/actuator/metrics/user.registrations
curl http://localhost:8080/actuator/metrics/api.requests.duration

# Build the image
docker build -t project:latest .

# Run with environment variables
docker run -d \
  -p 8080:8080 \
  -e SPRING_PROFILES_ACTIVE=prod \
  -e DATABASE_URL=jdbc:postgresql://db:5432/project \
  -e JWT_SECRET=your-secret-key \
  project:latest

# Apply Kubernetes manifests
kubectl apply -f k8s/

# Check deployment status
kubectl get pods -l app=project

# View logs
kubectl logs -f deployment/project

# Database configuration
spring.datasource.url=${DATABASE_URL:jdbc:postgresql://localhost:5432/project}
spring.datasource.username=${DATABASE_USERNAME:project}
spring.datasource.password=${DATABASE_PASSWORD:password}
spring.datasource.hikari.maximum-pool-size=20
# JPA configuration
spring.jpa.hibernate.ddl-auto=validate
spring.jpa.show-sql=false
spring.jpa.properties.hibernate.format_sql=true
spring.jpa.properties.hibernate.jdbc.batch_size=20
# Redis configuration
spring.cache.type=redis
spring.data.redis.host=${REDIS_HOST:localhost}
spring.data.redis.port=${REDIS_PORT:6379}
spring.data.redis.timeout=2000ms

# Format code
./mvnw spotless:apply

# Validate code style
./mvnw checkstyle:check

# Run quality checks
./mvnw sonar:sonar

## Phase 6: Documentation Site Generation

### 6.1 Maven Site Configuration

```xml
<plugin>
    <groupId>org.apache.maven.plugins</groupId>
    <artifactId>maven-site-plugin</artifactId>
    <version>4.0.0-M13</version>
    <configuration>
        <locales>en</locales>
        <inputEncoding>UTF-8</inputEncoding>
        <outputEncoding>UTF-8</outputEncoding>
        <siteDirectory>${basedir}/src/site</siteDirectory>
    </configuration>
    <dependencies>
        <dependency>
            <groupId>org.asciidoctor</groupId>
            <artifactId>asciidoctor-maven-plugin</artifactId>
            <version>2.2.4</version>
        </dependency>
    </dependencies>
</plugin>

src/site/asciidoc/
├── index.adoc              # Main documentation page
├── getting-started/
│   ├── installation.adoc   # Installation instructions
│   └── quick-start.adoc    # Quick start guide
├── user-guide/
│   ├── api-reference.adoc  # API documentation
│   └── configuration.adoc  # Configuration reference
├── developer-guide/
│   ├── architecture.adoc   # Architecture overview
│   ├── testing.adoc        # Testing guide
│   └── contributing.adoc   # Contributing guidelines
└── deployment/
    ├── docker.adoc         # Docker deployment
    └── kubernetes.adoc     # Kubernetes deployment

#!/bin/bash
# docs/build.sh - Complete documentation generation script

set -e

echo "🚀 Generating comprehensive project documentation..."

# 1. Generate Javadoc
echo "📚 Generating Javadoc..."
./mvnw javadoc:javadoc -Dquiet=true

# 2. Generate API documentation
echo "🔧 Generating API documentation..."
./mvnw spring-boot:run -Dspring-boot.run.arguments="--spring.profiles.active=docs" &
APP_PID=$!
sleep 30  # Wait for app startup

curl -o docs/api/openapi.json http://localhost:8080/v3/api-docs
kill $APP_PID

# 3. Generate architecture diagrams
echo "📐 Generating architecture diagrams..."
python scripts/generate-diagrams.py

# 4. Build documentation site
echo "🏗️ Building documentation site..."
./mvnw site:site -DgenerateReports=false

# 5. Generate coverage reports
echo "📊 Generating coverage reports..."
./mvnw jacoco:report

# 6. Copy all documentation to target directory
echo "📁 Assembling documentation..."
mkdir -p target/docs
cp -r target/site/apidocs target/docs/javadoc
cp -r target/site target/docs/site
cp docs/api/openapi.json target/docs/api/

echo "✅ Documentation generated successfully!"
echo "📖 View documentation: file://$(pwd)/target/docs/site/index.html"

docs/
├── api/
│   ├── openapi.json          # OpenAPI specification
│   ├── swagger-ui.html       # Interactive API docs
│   └── postman-collection.json # Postman collection
├── architecture/
│   ├── system-diagram.png    # System architecture diagram
│   ├── data-flow.png         # Data flow diagram
│   └── deployment-diagram.png # Deployment architecture
├── javadoc/                  # Generated Javadoc HTML
├── guides/
│   ├── user-guide.md         # End-user documentation
│   ├── developer-guide.md    # Developer documentation
│   └── deployment-guide.md   # Deployment instructions
└── README.md                 # Project README

# Generate all documentation for current project
/developer-kit-java:devkit.java.generate-docs

# Generate API documentation only
/developer-kit-java:devkit.java.generate-docs . api html

# Generate documentation for specific project
/developer-kit-java:devkit.java.generate-docs /path/to/project full markdown

# Generate architecture documentation
/developer-kit-java:devkit.java.generate-docs . architecture asciidoc