Works with the AI Agents you already use

    Claude CodeClaude CodeCursorCursorCodex CLICodex CLIMuseMuseDotsDots+22 more

    OpenAPI Swagger review

    0

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

    Free

    Security 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.

    How to use

    Skills on Agensi run inside your AI agent. Copy the prompt, paste it into your agent, and it connects to Agensi and installs this skill for you. If a payment is needed, your agent shows it to you first.

    Reviews

    No reviews yet

    Be one of the first to try it. Every listed skill passes our trust checks below.

    Security scanned

    Passed our 8-point scan before listing

    Fresh listing

    Recently published to Agensi

    Free forever

    No account required to browse

    Trust & safety

    Security scanned

    Verified clean 2 days ago

    • Free to download with an account

    Requires

    no tools needed. Web access only if pulling a spec remotely.

    Listed2 days ago
    Updatedtoday

    What's inside

    Frequently Asked Questions