Works with the AI Agents you already use

    Claude CodeClaude CodeCursorCursorCodex CLICodex CLIMuseMuseDotsDots+21 more

    OpenAPI Swagger review

    0

    Audit OpenAPI and Swagger specs for code-generation readiness, missing types, and implementation drift.

    Free

    1 useSecurity scanned
    OpenAPI Swagger review

    OpenAPI Swagger review

    Example session with this skill installed

    Review my openapi.yaml for code-gen readiness. I want to generate a TypeScript client from this next.

    • Read your context and instructions
    • Compiled the openapi swagger review

    I have reviewed openapi.yaml. The spec is structurally sound but contains several blockers that will result in poor TypeScript method naming and missing error handling in your generated client.

    OpenAPI Review Report

    Worth keeping

    • Consistent Path Naming: All endpoints follow the plural noun convention.
    • Strong Typing: Most schemas avoid additionalProperties: true and use specific types.

    Findings

    SeverityLocationFindingRecommended Fix
    BlockerPOST /usersMissing operationId.Add operationId: createUser.
    BlockerGET /users/{id}Path parameter {id} has no matching parameter definition.Add name: id, in: path, required: true.
    HighAll endpointsMissing 401 and 403 responses despite global security.Add standard 401 error response referencing #/components/schemas/Error.
    HighGET /searchNo 429 rate-limit response documented for an expensive operation.Add 429 response with Retry-After header.
    Medium#/components/schemas/UserMissing example for the uuid field.Add example: "550e8400-e29b-41d4-a716-446655440000".
    LowGET /healthMissing description for the 200 response.Add description: "Service is healthy".

    Overall Maturity: Solid foundation with a few systemic gaps that will break code generation.

    Next steps

    1. Would you like me to apply the mechanical fixes (adding operationIds and standard error responses) now?
    2. Shall I generate a shared Error schema in components/schemas to deduplicate your response objects?
    3. Should I check your src/routes directory to verify this spec matches your actual implementation?

    Connects securely to your tools. The creator never sees your data.

    About this skill

    A valid OpenAPI specification can still be a failure for code generation. Vague types, missing error shapes, and inconsistent naming get faithfully reproduced in generated clients, leading to broken builds or manual cleanup. This skill reviews specs through the lens of machine-readability and generation readiness.

    What it does

    • Identity & routing audit ensures unique operationIds and parameter-to-path template alignment.
    • Schema verification flags untyped objects, missing required arrays, and ambiguous nullability.
    • Response modeling checks for 2xx schema presence and standard error shapes for 4xx/5xx codes.
    • Synthetic-data readiness evaluates if a spec is self-contained enough to generate realistic mock data.
    • Drift detection compares the specification against actual source code routes and handlers when available.
    • Security pattern analysis identifies weak auth patterns, sensitive data in URLs, and credential leaking.

    How it works

    1. Locate and load the spec file from common locations like /docs or the project root.
    2. Structural validation runs via CLI tools or manual parsing to ensure the YAML/JSON is sound.
    3. Checklist execution performs a comprehensive pass across all operations based on severity-ranked criteria.
    4. Report generation delivers a categorized list of blockers, high, medium, and low severity findings.

    Frameworks & tools

    Works with OpenAPI 3.x and Swagger 2.0 specifications in YAML or JSON. Integrates with redocly/cli, swagger-cli, or Python-based spec validators for structural checks.

    Why this beats prompting it yourself

    Generic prompts often miss the subtle behavioral gaps like missing 429 retry headers or synthetic data referential integrity. This skill uses a tiered severity system specifically tuned for code-generation outcomes, ensuring you fix blockers before polish.

    Use cases

    • Auditing a newly generated spec before using it to scaffold a frontend client.
    • Identifying drift between a legacy API's documentation and its actual implementation.
    • Strengthening a spec's data models to allow for automated mock server generation.
    • Enforcing consistent naming conventions across a large, multi-file API definition.

    Known limitations

    Does not perform dynamic security testing or detect logic-level authorization bugs. resolving external $ref pointers requires the referenced files to be present in the accessible workspace.

    Does not perform dynamic security testing. Resolving external $ref pointers requires referenced files to be present in the workspace. Cannot fix judgment-based naming issues without approval.

    How to use

    1. 1

      Connect your agent to the Agensi MCP

      Copy the prompt and paste it into Claude, ChatGPT, Cursor or any agent that supports MCP. It sets up the connection for you. Manual setup

    2. 2

      Sign in to Agensi

      Your agent shows a sign-in link. Sign in and click Allow.

    3. 3

      Ask for what you need

      Your agent loads this skill and uses it on your task. It always asks before any payment.

    Reviews

    No reviews yet

    Be one of the first to try it. Every listed skill goes through the trust checks below.

    Security scanned

    Checked by our 8-point scan before listing

    1 use

    Times used to date

    Free forever

    No account required to browse

    Trust & safety

    Security scan

    Security scan passed 1 month ago

    • Free with an Agensi account

    Permissions

    No special permissions declared or detected

    Listed1 month ago
    Updated28 days ago

    What's inside

    Frequently Asked Questions

    This skill specifically audits specs for 'code-generation readiness.' While standard linters check for syntax, this tool identifies issues like vague types and inconsistent naming that cause broken builds or poor developer experiences in generated SDKs.

    The skill is compatible with OpenAPI 3.x and Swagger 2.0 specifications in both YAML and JSON formats. It can process local files, including multi-file definitions, provided all referenced $ref pointers are within the accessible workspace.

    To use this skill, simply point it to your specification file or project root; it automatically locates common documentation directories. It integrates with existing tools like Redocly or swagger-cli to perform its initial structural validation. You can also point it to a public web page.

    Yes, it includes a drift detection feature that compares your specification against existing source code routes and handlers. This ensures your documentation reflects the actual implementation and flags any undocumented endpoints or parameter mismatches.

    No, the skill focuses on static analysis and specification quality. It does not perform dynamic security testing (DAST) or identify logical flaws in your API's authorization code.

    New in Technical Documentation