spring-boot-openapi-documentation — independently scanned and version-tracked by SaferSkills.
SaferSkills independently audited spring-boot-openapi-documentation (Agent Skill) and scored it 100/100 (green). The audit ran 55 deterministic rules across Security, Supply Chain, Maintenance, Transparency, and Community; it found 0 high-severity and 0 lower-severity findings. The full rule-by-rule trace and per-finding evidence are below. Free, methodology-open.
Findings & checks · 0 flagged
Every scanned point with the score it earned and what moved between them.
First recorded scan — no prior version to compare against.
The primary manifest — the file an agent reads to learn what this artifact does.
SpringDoc OpenAPI automates generation of OpenAPI 3.0 documentation for Spring Boot projects with a Swagger UI web interface for exploring and testing APIs.
| Concept | Description |
|---|---|
| Dependencies | springdoc-openapi-starter-webmvc-ui for WebMvc, springdoc-openapi-starter-webflux-ui for WebFlux |
| Configuration | application.yml with springdoc.api-docs.* and springdoc.swagger-ui.* properties |
| Access Points | OpenAPI JSON: /v3/api-docs, Swagger UI: /swagger-ui/index.html |
| Core Annotations | @Tag, @Operation, @ApiResponse, @Parameter, @Schema, @SecurityRequirement |
| Security | Configure security schemes in OpenAPI bean, apply with @SecurityRequirement |
| Pagination | Use @ParameterObject with Spring Data Pageable |
Add SpringDoc starter for your application type (WebMvc or WebFlux). See dependency-setup.md for Maven/Gradle configuration.
Set basic configuration in application.yml:
springdoc:
api-docs:
path: /api-docs
swagger-ui:
path: /swagger-ui.html
operationsSorter: methodSee configuration.md for advanced options.
Use OpenAPI annotations to add descriptive information:
@RestController
@Tag(name = "Book", description = "Book management APIs")
public class BookController {
@Operation(summary = "Get book by ID")
@ApiResponse(responseCode = "200", description = "Book found")
@GetMapping("/{id}")
public Book findById(@PathVariable Long id) { }
}See controller-documentation.md for patterns.
Apply @Schema annotations to DTOs:
@Schema(description = "Book entity")
public class Book {
@Schema(example = "1", accessMode = Schema.AccessMode.READ_ONLY)
private Long id;
@Schema(example = "Clean Code", required = true)
private String title;
}See model-documentation.md for validation patterns.
Set up security schemes in OpenAPI bean:
@Bean
public OpenAPI customOpenAPI() {
return new OpenAPI()
.components(new Components()
.addSecuritySchemes("bearer-jwt", new SecurityScheme()
.type(SecurityScheme.Type.HTTP)
.scheme("bearer")
.bearerFormat("JWT")
)
);
}Apply with @SecurityRequirement(name = "bearer-jwt") on controllers. See security-configuration.md.
Use @ParameterObject for Spring Data Pageable:
@GetMapping("/paginated")
public Page<Book> findAll(@ParameterObject Pageable pageable) {
return repository.findAll(pageable);
}Access Swagger UI at /swagger-ui/index.html to verify documentation completeness.
Configure API grouping, versioning, and build plugins. See advanced-configuration.md and build-integration.md.
@ExampleObject for realistic examples@SecurityRequirement where authentication needed@Hidden or create separate API groups@Schema annotations@SecurityRequirement annotations@Operation(hidden = true)) are still visible in code and may leak through other documentation tools@RestController
@Tag(name = "Books", description = "Book management APIs")
@RequestMapping("/api/books")
public class BookController {
@Operation(
summary = "Get book by ID",
description = "Retrieves detailed information about a specific book"
)
@ApiResponse(responseCode = "200", description = "Book found")
@ApiResponse(responseCode = "404", description = "Book not found")
@GetMapping("/{id}")
public Book getBook(@PathVariable Long id) {
return bookService.findById(id);
}
@Operation(summary = "Create new book")
@SecurityRequirement(name = "bearer-jwt")
@PostMapping
@ResponseStatus(HttpStatus.CREATED)
public Book createBook(@Valid @RequestBody CreateBookRequest request) {
return bookService.create(request);
}
}@Schema(description = "Book entity")
public class Book {
@Schema(description = "Unique identifier", example = "1", accessMode = Schema.AccessMode.READ_ONLY)
private Long id;
@Schema(description = "Book title", example = "Clean Code", required = true)
@NotBlank
@Size(min = 1, max = 200)
private String title;
@Schema(description = "Author name", example = "Robert C. Martin")
@NotBlank
private String author;
@Schema(description = "Price in USD", example = "29.99", minimum = "0")
@NotNull
@DecimalMin("0.0")
private BigDecimal price;
}@Bean
public OpenAPI customOpenAPI() {
return new OpenAPI()
.info(new Info()
.title("Book API")
.version("1.0.0")
.description("REST API for book management"))
.components(new Components()
.addSecuritySchemes("bearer-jwt", new SecurityScheme()
.type(SecurityScheme.Type.HTTP)
.scheme("bearer")
.bearerFormat("JWT"))
.addSecuritySchemes("api-key", new SecurityScheme()
.type(SecurityScheme.Type.APIKEY)
.in(SecurityScheme.In.HEADER)
.name("X-API-Key")));
}spring-boot-rest-api-standards — REST API design standardsspring-boot-dependency-injection — Dependency injection patternsunit-test-controller-layer — Testing REST controllersspring-boot-actuator — Production monitoring and management~30 seconds. Free. No account. Every finding cites a rule and a line of evidence.