spring-boot-openapi-documentation
tessl i github:giuseppe-trisciuoglio/developer-kit --skill spring-boot-openapi-documentationGenerate comprehensive REST API documentation using SpringDoc OpenAPI 3.0 and Swagger UI in Spring Boot 3.x applications. Use when setting up API documentation, configuring Swagger UI, adding OpenAPI annotations, implementing security documentation, or enhancing REST endpoints with examples and schemas.
Validation
69%| Criteria | Description | Result |
|---|---|---|
skill_md_line_count | SKILL.md is long (624 lines); consider splitting into references/ and linking | Warning |
allowed_tools_field | 'allowed-tools' contains unusual tool name(s) | Warning |
metadata_version | 'metadata' field is not a dictionary | Warning |
license_field | 'license' field is missing | Warning |
frontmatter_unknown_keys | Unknown frontmatter key(s) found; consider removing or moving to metadata | Warning |
Total | 11 / 16 Passed | |
Implementation
65%This skill provides highly actionable, executable code examples for SpringDoc OpenAPI integration with excellent coverage of common use cases. However, it suffers from verbosity in introductory sections and lacks a clear step-by-step workflow with validation checkpoints. The document would benefit from trimming redundant content and adding explicit verification steps.
Suggestions
Remove or significantly condense the 'When to Use' section - Claude can infer appropriate use cases from the skill title and content
Add a 'Quick Start Workflow' section with numbered steps and explicit validation: '1. Add dependency → 2. Add config → 3. Start app → 4. Verify: visit http://localhost:8080/swagger-ui/index.html'
Move 'Best Practices' and 'Common Annotations Reference' to separate reference files to reduce main document length
Remove version comments like '// Use latest stable version' - Claude knows to use current versions
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | The skill is comprehensive but includes some unnecessary verbosity, such as the extensive 'When to Use' section listing 15 bullet points that Claude could infer, and the 'Best Practices' section with 10 items that largely restate what's already shown in examples. The version comments like '// Use latest stable version' add noise. | 2 / 3 |
Actionability | Excellent actionable content with fully executable, copy-paste ready code examples throughout. Maven/Gradle dependencies, configuration files, and complete controller implementations are all concrete and immediately usable. | 3 / 3 |
Workflow Clarity | While individual code examples are clear, there's no explicit workflow sequence for setting up SpringDoc from scratch. Missing validation checkpoints - no guidance on verifying the setup works (e.g., 'After adding dependencies, start the app and verify Swagger UI loads at...'). | 2 / 3 |
Progressive Disclosure | References to external files exist (references/troubleshooting.md, references/springdoc-official.md) which is good, but the main document is quite long (~400 lines) with content that could be split out. The 'Common Annotations Reference' and 'Best Practices' sections could be separate reference files. | 2 / 3 |
Total | 9 / 12 Passed |
Activation
100%This is a well-crafted skill description that excels across all dimensions. It uses third person voice correctly, provides specific concrete actions, includes comprehensive trigger terms that users would naturally use, and has an explicit 'Use when...' clause. The technology-specific focus (Spring Boot 3.x, SpringDoc OpenAPI 3.0, Swagger UI) makes it highly distinctive.
| Dimension | Reasoning | Score |
|---|---|---|
Specificity | Lists multiple specific concrete actions: 'Generate comprehensive REST API documentation', 'setting up API documentation', 'configuring Swagger UI', 'adding OpenAPI annotations', 'implementing security documentation', 'enhancing REST endpoints with examples and schemas'. | 3 / 3 |
Completeness | Clearly answers both what ('Generate comprehensive REST API documentation using SpringDoc OpenAPI 3.0 and Swagger UI') AND when with explicit 'Use when...' clause covering multiple trigger scenarios. | 3 / 3 |
Trigger Term Quality | Excellent coverage of natural terms users would say: 'REST API documentation', 'SpringDoc', 'OpenAPI', 'Swagger UI', 'Spring Boot', 'API documentation', 'annotations', 'security documentation', 'endpoints', 'schemas'. | 3 / 3 |
Distinctiveness Conflict Risk | Very specific niche targeting Spring Boot 3.x with SpringDoc OpenAPI 3.0 and Swagger UI - unlikely to conflict with generic documentation skills or other framework-specific skills due to explicit technology stack mentions. | 3 / 3 |
Total | 12 / 12 Passed |
Reviewed
Table of Contents
Is this your skill?
If you maintain this skill, you can claim it as your own. Once claimed, you can manage eval scenarios, bundle related skills, attach documentation or rules, and ensure cross-agent compatibility.