What is OpenAPI/Swagger?
OpenAPI (formerly Swagger) is the contract that describes your REST endpoints, parameters, schemas, and responses. Because it is the source of truth for many teams, scanning it uncovers security and quality issues before code is deployed. Learn more on the official OpenAPI documentation.
Common issues in OpenAPI definitions
- Missing authentication: operations that lack security schemes or scopes.
- Unclear error responses: absent RFC 7807 structure or inconsistent status codes.
- Incomplete pagination: unbounded list endpoints that enable scraping.
- Sparse documentation: empty descriptions, no examples, and missing contact info.
How APISAST scans OpenAPI files
APISAST parses JSON or YAML specs and applies 29 static checks across security, documentation, error handling, versioning, and performance. It checks declared security requirements, documented rate limit headers, pagination parameters, and error response schemas. Findings include a location in the contract and guidance for improving it.
For a broader product view, see the API security scanner page.
What a contract finding looks like
Imagine a GET /orders operation with a 200 response but no pagination parameter. A collection can grow without an obvious bound, so the scanner flags the missing pagination declaration. Add a limit and cursor parameter, document the response metadata, then scan the updated file again. Our API pagination guide compares offset and cursor approaches.
A separate finding may identify an operation without a declared security requirement. That points you to the OpenAPI contract; it does not prove the running endpoint is unprotected. Check the implementation and add the appropriate security scheme to the spec. See the OAuth2 and JWT guide for a concrete example.
From upload to a useful review
- Upload a JSON or YAML OpenAPI or Swagger file, or provide a URL to the definition.
- Choose a scan profile and inspect the findings grouped by severity and endpoint.
- Update the contract, confirm the intended behaviour in the service, and scan again.
- Share the report with the API owner and use API SAST testing guidance to include contract checks in your review process.
What a static scan cannot confirm
A specification describes intended behaviour. It cannot show whether an API actually enforces object-level authorization, rotates tokens, or respects rate limits under load. Use integration tests and runtime monitoring for those questions. The rate limiting guide explains how to design the policy and test enforcement.
If the contract and implementation disagree, assign an owner and update the source of truth before closing a finding. Preserve the scan report and the runtime test result so reviewers can see what was changed.
Prepare a useful OpenAPI definition
Scan the same file that your team uses to generate documentation or client SDKs. Ensure the servers entry, operations, parameters, responses, and security schemes reflect the current service. A stale file can yield a clean report for routes that no longer exist while missing a newly deployed operation. If the contract is generated from code, produce it during the build and compare it with the committed or published copy before scanning.
Replace real tokens and personal data in examples with placeholders. APISAST saves the uploaded specification and report so the result can be reopened. Review your organisation's rules for sharing API definitions before submitting internal endpoints to a hosted instance. Use a dedicated secret scanner for literal credentials; APISAST focuses on design signals such as API keys in query parameters.
Interpret the severity and location
A report groups findings by rule and severity and points to a location in the specification. An error-severity rule, such as an HTTP server URL or an API key in a query parameter, deserves prompt review. An informational finding, such as a missing documented rate-limit header, may be a documentation gap. Do not change the API blindly to make every warning disappear. First confirm the intended behaviour with the owner, then edit the contract or implementation as appropriate.
For a collection without a recognised pagination parameter, add a bounded paging design and test it under load. For a missing security requirement, decide whether anonymous access is intentional and test the running route. Rescan the updated file, inspect the specific rule, and retain the report for review. A better score is useful feedback, but the verified behaviour is the evidence that closes a security issue.
Compliance and standards
- • RFC 7807 error bodies with type, title, status, detail, and instance.
- • Semantic versioning and deprecation flags for change control.
- • HTTPS enforcement and secure server definitions.
- • Consistent response schemas and examples for every status code.
Comparing open source and commercial scanners
OpenAPI linters help enforce a consistent contract. APISAST adds security and quality checks for common design signals, with exportable findings for review. Neither a linter nor a contract scanner replaces testing a running API against the OWASP API Security Top 10.
If you need an overview of static vs dynamic coverage, read the API security scanner comparison or explore API security SAST tools for process details.