Vai al contenuto

Step 09 — OpenAPI con springdoc¶

Obiettivo: documentazione API auto-generata + Swagger UI.

Dipendenza¶

<dependency>
    <groupId>org.springdoc</groupId>
    <artifactId>springdoc-openapi-starter-webmvc-ui</artifactId>
    <version>2.6.0</version>
</dependency>

Configurazione globale¶

SpringBootFromScratchApplication.java

@SpringBootApplication
@OpenAPIDefinition(
    info = @Info(
        title = "Spring Boot From Scratch API",
        version = "v1",
        description = "API REST per la gestione di progetti e task.",
        contact = @Contact(name = "Federico Calò", url = "https://federicocalo.dev"),
        license = @License(name = "MIT", url = "https://opensource.org/licenses/MIT")
    )
)
public class SpringBootFromScratchApplication { ... }

Annotazioni a livello endpoint¶

@RestController
@Tag(name = "Projects", description = "Gestione dei progetti")
public class ProjectController {

    @PostMapping
    @Operation(summary = "Crea un nuovo progetto")
    public ResponseEntity<ProjectResponse> create(@Valid @RequestBody ProjectRequest req) { ... }
}

URL utili¶

Spec JSON: http://localhost:8080/v3/api-docs
Spec YAML: http://localhost:8080/v3/api-docs.yaml
Swagger UI: http://localhost:8080/swagger-ui.html

Esercizi¶

Aggiungi esempi di request/response usando @ExampleObject.
Esponi un secondo server in OpenAPI per la prod (https://api.example.com).
Configura uno schema di sicurezza (Bearer JWT) per future API protette.

Riferimenti nel codice¶