Créer une API REST en Java avec Spring Boot et Claude Code (2026)

Créer une API REST en Java avec Spring Boot et Claude Code

Java reste, en 2026, l'un des langages les plus utilisés au monde pour les applications d'entreprise — et Spring Boot en est le framework roi côté backend. Robuste, mûr, adossé à un écosystème colossal, il permet de bâtir des API REST solides, sécurisées et maintenables. Son seul défaut ? Sa réputation de verbosité : configuration abondante, annotations en cascade, couches multiples (entité, repository, service, contrôleur). C'est précisément là que Claude Code change la donne.

Plutôt que d'écrire à la main chaque classe et chaque annotation, vous décrivez votre besoin en français — « une API REST pour gérer un catalogue de produits, avec CRUD complet et connexion PostgreSQL » — et l'agent génère le code Java, lance le build Maven, lit les erreurs du compilateur et les logs de démarrage Spring, puis se corrige jusqu'à obtenir un service qui tourne. Ce guide vous montre comment créer une API REST en Java avec Spring Boot et Claude Code de A à Z : installation, premier contrôleur, structuration en couches, base de données avec JPA, tests JUnit, gestion d'erreurs, conteneurisation et bonnes pratiques. Si vous débutez avec l'agent, gardez à portée notre guide complet de Claude Code.

Sommaire

Pourquoi Spring Boot et Claude Code font bon ménage<a id="pourquoi"></a>

Spring Boot repose sur des conventions très stables et un compilateur Java strict. Chaque erreur de type, chaque dépendance manquante, chaque annotation mal placée provoque un message précis — au moment de la compilation ou au démarrage du contexte Spring. Cette rigueur, parfois pesante pour l'humain, est une aubaine pour un agent de code : elle transforme chaque problème en signal exploitable.

Contrairement à un simple autocomplete, Claude Code est un agent : il lit vos fichiers, exécute mvn dans le terminal, interprète les résultats et itère. Appliqué à Spring Boot, cela donne une boucle d'auto-correction efficace. L'agent écrit un contrôleur, lance mvn spring-boot:run, lit le log si le bean ne se câble pas, comprend le problème d'injection ou de mapping, et corrige. Le typage fort de Java et la validation du contexte Spring au démarrage ferment la boucle de vérification — l'application refuse de démarrer si le graphe de dépendances est incohérent, ce qui donne à l'agent un retour immédiat.

Cette philosophie prolonge naturellement d'autres usages backend de l'agent. Si vous avez déjà lu notre tutoriel pour créer une API en Python avec FastAPI, vous retrouverez ici la même logique « décrire, générer, compiler, corriger » — appliquée à un écosystème plus verbeux mais extrêmement normé, où les conventions Spring guident l'agent à chaque étape.

Prérequis avant de commencer<a id="prerequis"></a>

Avant de générer votre première API Spring Boot avec l'agent, réunissez quatre éléments :

Un réflexe utile dès le départ : ne mettez jamais de secrets (URL de base, mot de passe) en dur dans le code ni dans le dépôt. Demandez à l'agent de les lire depuis des variables d'environnement, injectées dans application.properties.

Générer son premier contrôleur REST<a id="premier-controleur"></a>

Lancez Claude Code dans votre dossier et formulez une demande précise :

« Crée un projet Spring Boot nommé catalog-api avec Maven, Java 21, les dépendances Spring Web et Spring Boot Actuator. Expose une route GET /ping qui renvoie un JSON {"message":"pong"}. Lance mvn spring-boot:run pour vérifier que le serveur démarre sur le port 8080. »

L'agent génère le pom.xml, la classe principale et le contrôleur, puis compile. Le résultat ressemble à ceci :

package com.example.catalog;

import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RestController;
import java.util.Map;

@RestController
public class PingController {

    @GetMapping("/ping")
    public Map<String, String> ping() {
        return Map.of("message", "pong");
    }
}

En quelques lignes, tout est là : l'annotation @RestController déclare un contrôleur REST, @GetMapping mappe la route, et Spring sérialise automatiquement la Map en JSON via Jackson. Pas de configuration manuelle du serveur : Spring Boot embarque Tomcat et le démarre seul. L'agent vérifie ensuite avec un appel curl http://localhost:8080/ping.

Structurer le projet en couches<a id="structure"></a>

Une API Spring Boot professionnelle suit une architecture en couches claire. Demandez à l'agent de l'organiser ainsi :

Ce découpage n'est pas cosmétique : il permet à l'agent de raisonner couche par couche et de tester chaque niveau isolément. Précisez-le une fois dans votre prompt ou votre CLAUDE.md, et Claude Code respectera cette organisation pour chaque nouvelle fonctionnalité. Un bon prompt : « Génère l'entité Product (id, name, price, stock), son repository, un service ProductService et un contrôleur REST /api/products exposant le CRUD complet, avec des DTO pour l'entrée et la sortie. »

Brancher PostgreSQL avec Spring Data JPA<a id="base-de-donnees"></a>

La persistance est l'un des grands atouts de Spring Boot. Formulez votre demande :

« Connecte l'API à PostgreSQL avec Spring Data JPA et Hibernate. Lis l'URL, l'utilisateur et le mot de passe depuis des variables d'environnement. Configure Hibernate en mode validate et ajoute Flyway pour les migrations. »

L'agent ajoute les dépendances, configure le fichier de propriétés et crée la couche de persistance. Le application.properties ressemble à ceci :

spring.datasource.url=${DB_URL}
spring.datasource.username=${DB_USER}
spring.datasource.password=${DB_PASSWORD}
spring.jpa.hibernate.ddl-auto=validate
spring.jpa.properties.hibernate.dialect=org.hibernate.dialect.PostgreSQLDialect

L'entité et le repository sont d'une concision remarquable :

@Entity
@Table(name = "products")
public class Product {
    @Id
    @GeneratedValue(strategy = GenerationType.IDENTITY)
    private Long id;
    private String name;
    private BigDecimal price;
    private int stock;
    // getters / setters
}

public interface ProductRepository extends JpaRepository<Product, Long> {
    List<Product> findByNameContainingIgnoreCase(String name);
}

Le point fort ici : en héritant de JpaRepository, vous obtenez gratuitement les opérations CRUD (findAll, findById, save, deleteById), et Spring Data génère automatiquement la requête à partir du nom de méthode findByNameContainingIgnoreCase. L'agent exploite pleinement cette magie des conventions. Notez l'usage de ddl-auto=validate couplé à Flyway : le schéma est piloté par des migrations versionnées, pas par Hibernate — une bonne pratique indispensable en production.

Faire écrire les tests par l'agent<a id="tests"></a>

L'écosystème de test de Java est l'un des plus mûrs qui soient. Demandez à l'agent : « Écris des tests d'intégration pour le contrôleur avec MockMvc et des tests unitaires pour ProductService avec Mockito. » Il génère des classes annotées @WebMvcTest ou @SpringBootTest :

@WebMvcTest(ProductController.class)
class ProductControllerTest {

    @Autowired
    private MockMvc mockMvc;

    @MockBean
    private ProductService productService;

    @Test
    void getProduct_returnsOk() throws Exception {
        when(productService.findById(1L))
            .thenReturn(new ProductDto(1L, "Clavier", new BigDecimal("49.90"), 12));

        mockMvc.perform(get("/api/products/1"))
            .andExpect(status().isOk())
            .andExpect(jsonPath("$.name").value("Clavier"));
    }
}

L'agent lance mvn test, lit la sortie et corrige tant que le vert n'est pas atteint. Vous pouvez aller plus loin et adopter une approche TDD en lui demandant d'écrire le test avant l'implémentation — une méthode que nous détaillons dans notre guide pour écrire des tests unitaires en TDD avec Claude Code. Cette discipline paie doublement avec l'IA : le test devient une spécification exécutable que l'agent vise, et un filet de sécurité contre les régressions.

Une gestion d'erreurs propre et centralisée<a id="erreurs"></a>

Une API sérieuse ne renvoie jamais une trace d'exception brute au client. Demandez à l'agent de centraliser la gestion des erreurs avec @RestControllerAdvice :

@RestControllerAdvice
public class GlobalExceptionHandler {

    @ExceptionHandler(ProductNotFoundException.class)
    public ResponseEntity<Map<String, String>> handleNotFound(ProductNotFoundException ex) {
        return ResponseEntity.status(HttpStatus.NOT_FOUND)
            .body(Map.of("error", ex.getMessage()));
    }
}

Couplé à Bean Validation (@Valid sur les DTO d'entrée, @NotBlank, @Positive sur les champs), ce mécanisme garantit des réponses HTTP cohérentes : 404 pour une ressource absente, 400 pour une entrée invalide. L'agent sait câbler l'ensemble ; à vous de vérifier que chaque cas d'erreur métier est bien couvert. Cette rigueur sur les contrats d'API est aussi ce qui fait la valeur des plateformes de données modernes : le service immoapi.app, par exemple, illustre bien l'intérêt d'API REST bien documentées et à la gestion d'erreurs prévisible pour exposer des données métier fiables.

Conteneuriser et déployer<a id="docker"></a>

Une application Spring Boot se package en un JAR exécutable autonome, idéal pour Docker. Demandez : « Génère un Dockerfile multi-stage qui construit le JAR avec Maven puis produit une image légère basée sur un JRE. » L'agent produit un Dockerfile en deux étapes :

FROM maven:3.9-eclipse-temurin-21 AS build
WORKDIR /app
COPY . .
RUN mvn -q clean package -DskipTests

FROM eclipse-temurin:21-jre-alpine
COPY --from=build /app/target/*.jar app.jar
EXPOSE 8080
ENTRYPOINT ["java", "-jar", "/app.jar"]

Le premier étage compile et empaquette, le second ne conserve que le JAR sur une image jre-alpine minimale — l'image finale reste compacte et réduit la surface d'attaque. Pour approfondir cette étape, notre guide Claude Code et Docker applique la même logique à d'autres stacks. L'agent peut ensuite générer un pipeline CI/CD, ou automatiser vos commits et branches comme le montre notre article sur Git avec Claude Code.

Un CLAUDE.md taillé pour Spring Boot<a id="claude-md"></a>

Le meilleur investissement pour rendre l'agent fiable et cohérent sur la durée tient dans un fichier : CLAUDE.md, placé à la racine et lu à chaque session. Il transmet vos conventions sans que vous ayez à les répéter :

## Conventions Spring Boot pour ce projet
- Java 21, build Maven, framework : Spring Boot 3.x
- Architecture en couches : entity / repository / service / controller / dto
- Base : PostgreSQL via Spring Data JPA, schéma piloté par Flyway (ddl-auto=validate)
- Erreurs : @RestControllerAdvice centralisé, jamais de trace brute exposée
- Validation des DTO d'entrée avec Bean Validation (@Valid)
- Config lue depuis variables d'environnement, jamais de secret en dur
- Avant tout commit : mvn spotless:apply, mvn test

Avec ces quelques lignes, l'agent respecte votre découpage, importe les bonnes dépendances et lance les contrôles adéquats. Pour aller plus loin sur ce fichier central, consultez notre guide complet du fichier CLAUDE.md. Vous pouvez même créer des sous-agents spécialisés — un pour la couche persistance, un pour la revue de sécurité. Cette logique d'agents spécialisés et d'automatisation avancée est explorée en profondeur sur formation-openclaw.com, dédié aux agents IA open-source et à leur auto-hébergement en entreprise.

Vidéo : Claude Code en action

Pour visualiser la méthode de travail avec l'agent avant de vous lancer sur votre propre API Spring Boot, cette vidéo montre le workflow de bout en bout — décrire, générer, corriger — qui s'applique directement à ce tutoriel :

Limites et pièges à connaître<a id="limites"></a>

Coupler une IA à votre développement Spring Boot appelle quelques précautions lucides :

Gardées en tête, ces limites ne remettent pas en cause l'intérêt de l'approche : elles définissent le cadre d'un usage professionnel et sûr.

Passez à la vitesse supérieure

Vous savez désormais créer une API REST en Java avec Spring Boot et Claude Code : du premier contrôleur à l'architecture en couches, en passant par PostgreSQL avec Spring Data JPA, les tests JUnit et MockMvc, une gestion d'erreurs centralisée et un Dockerfile multi-stage. Java et Spring Boot restent des piliers de l'entreprise ; couplés à Claude Code, leur verbosité légendaire cesse d'être un frein — l'agent écrit les couches répétitives, respecte les conventions et boucle sur les erreurs du compilateur, pendant que vous vous concentrez sur la logique métier.

Reste l'étape suivante : transformer cette productivité en un véritable levier pour déléguer à l'IA une part croissante de votre travail.

👉 Découvrez comment déléguer une grande partie de votre travail à l'IA et vous concentrer sur l'essentiel : se faire remplacer par l'IA.

---

*Cet article fait partie de notre série de guides pratiques sur Claude Code. Pour aller plus loin, explorez le guide complet de Claude Code et notre tutoriel créer une API en Python avec FastAPI.*