Managing Swagger

Swagger/OpenAPI Management Skill

Manage OpenAPI specifications, validate schemas, generate code, and analyze API structures.

Core Helper Functions

#!/bin/bash

# Swagger/OpenAPI tooling paths
SWAGGER_CLI="${SWAGGER_CLI:-swagger-cli}"
OPENAPI_GENERATOR="${OPENAPI_GENERATOR:-openapi-generator-cli}"

# Validate spec and return structured result
validate_spec() {
    local spec_file="$1"
    $SWAGGER_CLI validate "$spec_file" 2>&1
}

# Parse spec with yq/jq depending on format
parse_spec() {
    local spec_file="$1"
    if [[ "$spec_file" == *.yaml ]] || [[ "$spec_file" == *.yml ]]; then
        yq eval -o=json "$spec_file"
    else
        jq '.' "$spec_file"
    fi
}

# Extract OpenAPI version
spec_version() {
    local spec_file="$1"
    parse_spec "$spec_file" | jq -r '.openapi // .swagger // "unknown"'
}

MANDATORY: Discovery-First Pattern

Always validate and analyze the spec before performing operations.

Phase 1: Discovery

#!/bin/bash
SPEC_FILE="${1:?Spec file path required}"

echo "=== Spec Overview ==="
parse_spec "$SPEC_FILE" | jq '{
    title: .info.title,
    version: .info.version,
    openapi_version: (.openapi // .swagger),
    description: (.info.description // "none")[0:100],
    contact: .info.contact,
    license: .info.license.name,
    servers: [(.servers // [])[] | .url],
    total_paths: (.paths | length),
    total_schemas: ((.components.schemas // .definitions) | length)
}'

echo ""
echo "=== Validation ==="
validate_spec "$SPEC_FILE"

echo ""
echo "=== Endpoints Summary ==="
parse_spec "$SPEC_FILE" | jq '[.paths | to_entries[] | {path: .key, methods: (.value | keys | map(select(. != "parameters")))}]'

Output Rules

• TOKEN EFFICIENCY: Target <=50 lines per output
• Summarize schemas rather than dumping full definitions
• Group endpoints by tags or path prefixes for readability

Common Operations

Spec Validation and Linting

#!/bin/bash
SPEC_FILE="${1:?Spec file path required}"

echo "=== Structural Validation ==="
validate_spec "$SPEC_FILE"

echo ""
echo "=== Missing Descriptions ==="
parse_spec "$SPEC_FILE" | jq '{
    paths_without_summary: [.paths | to_entries[] | .value | to_entries[] | select(.value.summary == null and .key != "parameters") | .key] | length,
    schemas_without_description: [(.components.schemas // .definitions // {}) | to_entries[] | select(.value.description == null) | .key],
    params_without_description: [.paths | .. | .parameters? // [] | .[] | select(.description == null) | .name] | unique
}'

echo ""
echo "=== Security Definitions ==="
parse_spec "$SPEC_FILE" | jq '{
    security_schemes: (.components.securitySchemes // .securityDefinitions // {}),
    global_security: (.security // []),
    unsecured_endpoints: [.paths | to_entries[] | .value | to_entries[] | select(.value.security == [] or (.value.security == null and .key != "parameters")) | .key] | length
}'

echo ""
echo "=== Deprecated Endpoints ==="
parse_spec "$SPEC_FILE" | jq '[.paths | to_entries[] | {path: .key, methods: [.value | to_entries[] | select(.value.deprecated == true) | .key]}| select(.methods | length > 0)]'

Schema Analysis

#!/bin/bash
SPEC_FILE="${1:?Spec file path required}"

echo "=== Schema Overview ==="
parse_spec "$SPEC_FILE" | jq '{
    total_schemas: ((.components.schemas // .definitions // {}) | length),
    schemas: [(.components.schemas // .definitions // {}) | to_entries[] | {
        name: .key,
        type: .value.type,
        required_fields: (.value.required // []) | length,
        total_properties: (.value.properties // {} | length),
        has_example: (.value.example != null)
    }]
}'

echo ""
echo "=== Schema Relationships (References) ==="
parse_spec "$SPEC_FILE" | jq '[(.components.schemas // .definitions // {}) | to_entries[] | {
    schema: .key,
    references: [.value | .. | .["$ref"]? // empty | split("/") | last] | unique
}] | map(select(.references | length > 0))'

echo ""
echo "=== Enum Values ==="
parse_spec "$SPEC_FILE" | jq '[(.components.schemas // .definitions // {}) | to_entries[] | .value.properties // {} | to_entries[] | select(.value.enum) | {field: .key, enum: .value.enum}]'

Code Generation

#!/bin/bash
SPEC_FILE="${1:?Spec file path required}"

echo "=== Available Generators ==="
$OPENAPI_GENERATOR list | head -30

echo ""
echo "=== Generate Client Example ==="
LANGUAGE="${2:-typescript-axios}"
OUTPUT_DIR="${3:-./generated}"
echo "Command to generate ${LANGUAGE} client:"
echo "  $OPENAPI_GENERATOR generate -i ${SPEC_FILE} -g ${LANGUAGE} -o ${OUTPUT_DIR}"

echo ""
echo "=== Generator Config Options ==="
$OPENAPI_GENERATOR config-help -g "${LANGUAGE}" 2>/dev/null | head -30

echo ""
echo "=== Spec Compatibility Check ==="
spec_ver=$(spec_version "$SPEC_FILE")
echo "Spec version: ${spec_ver}"
if [[ "$spec_ver" == 2* ]]; then
    echo "WARNING: Swagger 2.0 spec. Consider converting to OpenAPI 3.x for broader generator support."
    echo "Convert command: $SWAGGER_CLI convert ${SPEC_FILE} -o converted-spec.json"
fi

API Surface Analysis

#!/bin/bash
SPEC_FILE="${1:?Spec file path required}"

echo "=== API Surface by Tag ==="
parse_spec "$SPEC_FILE" | jq '[.paths | to_entries[] | .value | to_entries[] | select(.key != "parameters") | {method: .key, tags: (.value.tags // ["untagged"])}] | group_by(.tags[0]) | map({tag: .[0].tags[0], count: length, methods: [.[].method] | group_by(.) | map({method: .[0], count: length})})'

echo ""
echo "=== Request/Response Content Types ==="
parse_spec "$SPEC_FILE" | jq '{
    request_types: [.paths | .. | .requestBody?.content? // empty | keys] | flatten | unique,
    response_types: [.paths | .. | .responses? // {} | .[] | .content? // {} | keys] | flatten | unique
}'

echo ""
echo "=== Path Parameter Patterns ==="
parse_spec "$SPEC_FILE" | jq '[.paths | keys[] | select(test("\\{"))] | map({path: ., params: [match("\\{([^}]+)\\}"; "g") | .captures[0].string]})'

echo ""
echo "=== Pagination Patterns ==="
parse_spec "$SPEC_FILE" | jq '[.paths | to_entries[] | .value | to_entries[] | select(.value.parameters) | .value.parameters[] | select(.name | test("page|limit|offset|cursor|skip|take"; "i")) | {name, in: .in, type: (.schema.type // .type)}] | unique_by(.name)'

Safety Rules

• Read-only by default: Only validate and analyze specs; do not modify without confirmation
• Never run code generators that overwrite existing directories without user confirmation
• Validate before generating: Always validate the spec before running code generation
• Version check: Confirm OpenAPI version compatibility with the target generator
• Backup specs: Before any spec transformation, confirm the original is backed up

Output Format

Present results as a structured report:

Managing Swagger Report
═══════════════════════
Resources discovered: [count]

Resource       Status    Key Metric    Issues
──────────────────────────────────────────────
[name]         [ok/warn] [value]       [findings]

Summary: [total] resources | [ok] healthy | [warn] warnings | [crit] critical
Action Items: [list of prioritized findings]

Target ≤50 lines of output. Use tables for multi-resource comparisons.

Anti-Hallucination Rules

1. NEVER assume resource names — always discover via CLI/API in Phase 1 before referencing in Phase 2.
2. NEVER fabricate metric names or dimensions — verify against the service documentation or --help output.
3. NEVER mix CLI commands between service versions — confirm which version/API you are targeting.
4. ALWAYS use the discovery → verify → analyze chain — every resource referenced must have been discovered first.
5. ALWAYS handle empty results gracefully — an empty response is valid data, not an error to retry.

Counter-Rationalizations

Common Pitfalls

• Circular references: Deeply nested $ref cycles cause validators and generators to fail or loop
• Swagger 2.0 vs OpenAPI 3.x: Many tools only support one version; check before using
• allOf/oneOf/anyOf: Complex schema composition can produce unexpected generated code
• Server URL templates: Parameterized server URLs need variable values for code generation
• Spec drift: Generated code goes stale when the spec changes; integrate generation into CI/CD