OpenAPI Specs

API Security Testing uses your OpenAPI specification as the foundation for scanning. This page covers supported formats, limitations, and best practices for getting the most out of spec-driven testing.

Supported Formats

Only .json files are accepted. If your spec is in YAML format, convert it to JSON before uploading. You can use tools such as yq or online converters to do this:

# Using yq to convert YAML to JSON
yq -o=json eval openapi.yaml > openapi.json

Spec Requirements

For the best scan coverage, your OpenAPI spec should:

• Define all endpoints you want tested. Only endpoints present in the spec are scanned.
• Include request body schemas with accurate data types. The scanner uses these to generate valid base requests before injecting payloads.
• Specify parameter types (query, path, header, cookie) with correct formats and constraints.
• Document authentication schemes using the securityDefinitions (v2) or securitySchemes (v3) section.
• Use accurate example values where provided. The scanner may use examples as seed data for payload generation.

Handling Parsing Errors

When you upload a spec, Detectify validates it and reports any issues. Common parsing errors include:

• Invalid JSON syntax — Ensure the file is valid JSON. Use a JSON linter to check for syntax errors.
• Missing required fields — OpenAPI specs require certain fields such as info, paths, and openapi (or swagger for v2).
• Unresolved references — If your spec uses $ref to reference external files, inline those references before uploading. Detectify does not fetch external references.
• Unsupported features — Some advanced OpenAPI features such as oneOf discriminators or complex allOf compositions may not be fully supported.

If parsing fails, Detectify provides error details indicating the location and nature of the issue. Fix the reported problems in your spec and re-upload.

Best Practices

• Keep your spec up to date. An outdated spec means endpoints are missed during scanning.
• Include internal endpoints that are exposed to the network, not just public-facing ones.
• Use descriptive operation IDs to make scan results easier to interpret.
• Version your spec alongside your API code so scans always reflect the current state of the API.