validate-openapi-spec

---
name: validate-openapi-spec
description: Validates an OpenAPI/Swagger spec file for structure, required fields, and usability by the test generator. Use when the user wants to validate a spec, check if a spec is valid, or improve a spec for test generation.
license: MIT
---

# Validate OpenAPI spec

## When to use

Use this skill when the user:
- Asks to validate an OpenAPI or Swagger spec file
- Wants to check if a spec is valid or ready for the test generator
- Asks to improve or fix a spec for better test generation

## Workflow

1. **Identify the spec file.**  
   Use the file the user pointed at or the path they gave (under `sample-specs/`, `src/main/resources/sample-specs/`, or elsewhere).

2. **Check structure.**  
   - **OpenAPI 3.x:** Root must have `openapi` (e.g. `3.0.x`), `info`, and `paths`. Optionally `servers`, `components/schemas`, `security`.
   - **Swagger 2.0:** Root must have `swagger: "2.0"`, `info`, and `paths`.
   - **Format:** Valid JSON or YAML (no trailing commas, valid quoting). If YAML, ensure the project has a YAML parser (e.g. Jackson) and the file is loadable.

3. **Check paths and operations.**  
   - Each path should have at least one operation (get, post, put, delete, patch).
   - Operations should have `responses` with at least one status code (e.g. 200, 201). The generator uses these to propose test cases.
   - If the API requires auth, document `security` at operation or global level so generated tests can include auth.

4. **Suggest improvements for test generation.**  
   - Add response schemas or examples so generated assertions are more precise.
   - Document 4xx responses (400, 404, 401) where applicable so the generator produces negative tests.
   - Ensure `servers` or a base URL is documented if tests need a default base.

5. **Report.**  
   Summarize: valid or list of issues (e.g. missing `paths`, invalid JSON, missing responses). If valid, note any optional improvements. Do not include secrets; if the spec contains placeholders for keys, that is fine.

## Notes

- The project's generator may support only a subset of OpenAPI (e.g. paths, methods, response codes). Mention any generator-specific constraints if known.
- For quick validation, running the generator with the spec (`mvn exec:java -Dexec.args="--spec <path>"`) and checking for parse errors also validates that the spec is loadable.