Smart Endpoint Mapping - Complete Use Cases and Examples

This document provides comprehensive examples and use cases for the smart endpoint mapping functionality in swagger-coverage-cli. Smart mapping significantly improves API coverage accuracy by intelligently matching endpoints using advanced algorithms.

Quick Start
Status Code Priority Matching
Path and Parameter Matching
Confidence Scoring
Edge Cases and Error Handling
Real-World API Scenarios
Multi-API Support
CLI Integration Examples
Performance and Stress Testing
Best Practices

Quick Start

Smart mapping is enabled by default and provides improved coverage accuracy:

# Basic usage - smart mapping enabled automatically
swagger-coverage-cli api-spec.yaml collection.json

# With verbose output to see smart mapping statistics
swagger-coverage-cli api-spec.yaml collection.json --verbose

# With Newman reports
swagger-coverage-cli api-spec.yaml newman-report.json --newman

Coverage Improvement Example:

Before: 44.44% (8/18 operations matched)
After: 50.00% (9/18 operations matched)
Improvement: +5.56 percentage points

Status Code Priority Matching

Smart mapping prioritizes successful (2xx) status codes over error codes when multiple operations exist for the same endpoint.

Example 1: Basic Status Code Prioritization

API Specification:

paths:
  /users:
    get:
      operationId: getUsers
      responses:
        '200':
          description: Success
        '400':
          description: Bad Request
        '500':
          description: Server Error

Postman Test:

// Test only covers successful case
pm.test("Status code is 200", function () {
    pm.response.to.have.status(200);
});

Smart Mapping Result:

✅ Primary Match: GET /users (200) - Matched
❌ Secondary: GET /users (400) - Unmatched
❌ Secondary: GET /users (500) - Unmatched

Output:

Smart mapping: 1 primary matches, 0 secondary matches
Coverage: 33.33% (1/3 operations)

Example 2: Multiple Success Codes

API Specification:

paths:
  /users:
    post:
      operationId: createUser
      responses:
        '201':
          description: Created
        '202':
          description: Accepted
        '400':
          description: Bad Request

Postman Tests:

// Test covers multiple success codes
pm.test("Status code is 201 or 202", function () {
    pm.expect(pm.response.code).to.be.oneOf([201, 202]);
});

Smart Mapping Result:

✅ Primary Match: POST /users (201) - Matched
✅ Secondary Match: POST /users (202) - Matched
❌ Unmatched: POST /users (400) - Unmatched

Path and Parameter Matching

Smart mapping handles various path parameter naming conventions and patterns.

Example 3: Different Parameter Names

API Specification:

paths:
  /users/{userId}/profile:
    get:
      operationId: getUserProfile
      parameters:
        - name: userId
          in: path
          required: true
          schema:
            type: integer

Postman Request:

GET https://api.example.com/users/123/profile

Smart Mapping Result:

✅ Matched: /users/{userId}/profile matches /users/123/profile
🎯 Confidence: 1.0 (exact match)

Example 4: Complex Path Patterns

API Specification:

paths:
  /organizations/{orgId}/users/{userId}/permissions:
    get:
      operationId: getUserPermissions

Postman Request:

GET https://api.example.com/organizations/org123/users/user456/permissions

Smart Mapping Result:

✅ Matched: Complex path with multiple parameters
🎯 Confidence: 1.0 (all segments match)

Example 5: Versioned API Paths

API Specification:

paths:
  /v1/users/{id}:
    get:
      operationId: getUserV1
  /v2/users/{id}:
    get:
      operationId: getUserV2

Postman Requests:

GET https://api.example.com/v1/users/123
GET https://api.example.com/v2/users/456

Smart Mapping Result:

✅ V1 Match: /v1/users/{id} ← GET /v1/users/123
✅ V2 Match: /v2/users/{id} ← GET /v2/users/456
🎯 Confidence: 1.0 for both (exact version matching)

Confidence Scoring

Smart mapping assigns confidence scores (0.0-1.0) to matches based on multiple factors.

Example 6: Confidence Score Calculation

Factors Contributing to Confidence:

Method + Path Match: +0.6 base score
Exact Status Code Match: +0.3
Success Code Alignment: +0.2
Strict Validation Pass: +0.1

Scenario: Perfect Match

# API Spec
GET /users/{id} → 200

# Postman Test
GET /users/123 → Tests [200]

# Result
Confidence: 0.9 (0.6 + 0.3 = 0.9)

Scenario: Partial Match

# API Spec  
GET /users/{id} → 404

# Postman Test
GET /users/123 → Tests [200]

# Result
Confidence: 0.6 (0.6 base, no status code bonus)

Example 7: Confidence-Based Prioritization

Multiple Potential Matches:

# API Specs
GET /api/v1/users/{id} → 200
GET /api/v2/users/{id} → 200

# Postman Test
GET /api/v1/users/123 → Tests [200]

# Smart Mapping chooses higher confidence match
✅ GET /api/v1/users/{id} (Confidence: 1.0)
❌ GET /api/v2/users/{id} (Confidence: 0.0 - no match)

Edge Cases and Error Handling

Smart mapping gracefully handles various edge cases and malformed inputs.

Example 8: Malformed URLs

Input Scenarios:

// Test handles various malformed inputs gracefully
const malformedInputs = [
  'not-a-valid-url',
  '',
  null,
  undefined
];

// Smart mapping result: No crashes, graceful degradation

Example 9: Missing Status Codes

API Specification:

paths:
  /health:
    get:
      operationId: healthCheck
      # No explicit responses defined

Postman Test:

GET https://api.example.com/health → Tests [200]

Smart Mapping Result:

✅ Matched: Operations without status codes still match
🎯 Confidence: 0.7 (base + no-status-code bonus)

Example 10: Empty Collections

Scenario:

{
  "info": { "name": "Empty Collection" },
  "item": []
}

Smart Mapping Result:

Operations mapped: 0, not covered: 18
Smart mapping: 0 primary matches, 0 secondary matches
Coverage: 0.00%

Real-World API Scenarios

Examples covering common API patterns and architectural styles.

Example 11: RESTful CRUD Operations

API Specification:

paths:
  /users:
    get:
      operationId: listUsers
      responses:
        '200': { description: Success }
    post:
      operationId: createUser
      responses:
        '201': { description: Created }
  /users/{id}:
    get:
      operationId: getUser
      responses:
        '200': { description: Success }
    put:
      operationId: updateUser
      responses:
        '200': { description: Updated }
    delete:
      operationId: deleteUser
      responses:
        '204': { description: Deleted }

Postman Collection:

// Complete CRUD test suite
[
  { method: 'GET',    url: '/users',     expects: [200] },
  { method: 'POST',   url: '/users',     expects: [201] },
  { method: 'GET',    url: '/users/123', expects: [200] },
  { method: 'PUT',    url: '/users/123', expects: [200] },
  { method: 'DELETE', url: '/users/123', expects: [204] }
]

Smart Mapping Result:

Smart mapping: 5 primary matches, 0 secondary matches
Coverage: 100.00% (5/5 operations)
All CRUD operations successfully matched!

Example 12: Mixed Success and Error Codes

API Specification:

paths:
  /orders:
    post:
      operationId: createOrder
      responses:
        '201': { description: Created }
        '400': { description: Validation Error }
        '409': { description: Duplicate Order }
        '500': { description: Server Error }

Postman Tests:

// Tests multiple scenarios
[
  { name: 'Create Order - Success',       expects: [201] },
  { name: 'Create Order - Invalid Data', expects: [400] },
  { name: 'Create Order - Duplicate',    expects: [409] }
]

Smart Mapping Result:

✅ Primary Match:   POST /orders (201) - Success case prioritized
✅ Secondary Match: POST /orders (400) - Validation error tested
✅ Secondary Match: POST /orders (409) - Duplicate tested
❌ Unmatched:       POST /orders (500) - Server error not tested

Smart mapping: 1 primary matches, 2 secondary matches
Coverage: 75.00% (3/4 operations)

Multi-API Support

Smart mapping works seamlessly with multiple API specifications and microservices.

Example 13: Microservices Architecture

API Specifications:

# User Service (users-api.yaml)
paths:
  /users/{id}:
    get:
      operationId: getUser

# Profile Service (profiles-api.yaml)  
paths:
  /profiles/{userId}:
    get:
      operationId: getUserProfile

# Notification Service (notifications-api.yaml)
paths:
  /notifications:
    post:
      operationId: sendNotification

CLI Usage:

swagger-coverage-cli users-api.yaml,profiles-api.yaml,notifications-api.yaml collection.json --smart-mapping

Postman Collection:

[
  { name: 'Get User',          url: 'https://user-service.com/users/123' },
  { name: 'Get User Profile',  url: 'https://profile-service.com/profiles/123' },
  { name: 'Send Notification', url: 'https://notification-service.com/notifications' }
]

Smart Mapping Result:

User Service: 1/1 operations matched (100%)
Profile Service: 1/1 operations matched (100%)  
Notification Service: 1/1 operations matched (100%)

Overall Coverage: 100% (3/3 operations)
Smart mapping: 3 primary matches, 0 secondary matches

Example 14: API Gateway Aggregation

Gateway API Specification:

paths:
  /api/users/{id}:
    get:
      operationId: getUser
      tags: [Gateway, Users]
  /api/orders/{id}:
    get:
      operationId: getOrder
      tags: [Gateway, Orders]

Internal Service Specification:

paths:
  /users/{id}:
    get:
      operationId: getUserInternal
      tags: [Users, Internal]

Postman Tests:

[
  { name: 'Get User via Gateway', url: 'https://gateway.com/api/users/123' },
  { name: 'Get Order via Gateway', url: 'https://gateway.com/api/orders/456' },
  { name: 'Get User Direct', url: 'https://user-service.internal.com/users/123' }
]

Smart Mapping Result:

Gateway API: 2/2 operations matched (100%)
Internal API: 1/1 operations matched (100%)

Total Coverage: 100% (3/3 operations)
API separation maintained with smart mapping

Example 15: API Versioning Scenarios

Multiple API Versions:

# V1 API
paths:
  /v1/users:
    get:
      operationId: getUsersV1
    post:
      operationId: createUserV1

# V2 API  
paths:
  /v2/users:
    get:
      operationId: getUsersV2
    post:
      operationId: createUserV2

Postman Collection:

[
  { name: 'Get Users V1', url: '/v1/users' },
  { name: 'Create User V1', url: '/v1/users', method: 'POST' },
  { name: 'Get Users V2', url: '/v2/users' },
  { name: 'Create User V2', url: '/v2/users', method: 'POST' }
]

Smart Mapping Result:

V1 API: 2/2 operations matched (100%)
V2 API: 2/2 operations matched (100%)

Version-aware matching ensures no cross-contamination
Smart mapping: 4 primary matches, 0 secondary matches

CLI Integration Examples

Complete command-line usage examples for various scenarios.

Example 16: Basic Smart Mapping

# Smart mapping is enabled by default
swagger-coverage-cli api-spec.yaml collection.json --smart-mapping

# Output:
# Coverage: 50.00%
# HTML report saved to: coverage-report.html

Example 17: Verbose Smart Mapping

# Detailed output with statistics
swagger-coverage-cli api-spec.yaml collection.json --verbose

# Output:
# Specification loaded successfully: My API 1.0.0
# Extracted operations from the specification: 18
# Operations mapped: 9, not covered: 9
# Smart mapping: 6 primary matches, 3 secondary matches
# Coverage: 50.00%

Example 18: Smart Mapping with Strict Validation

# Combine smart mapping with strict validation
swagger-coverage-cli api-spec.yaml collection.json \
  \
  --strict-query \
  --strict-body \
  --verbose

# Output shows smart mapping working with strict validation:
# Smart mapping: 4 primary matches, 2 secondary matches
# Coverage: 75.00% (even with strict validation)

Example 19: Multi-API with Smart Mapping

# Multiple API specifications
swagger-coverage-cli users-api.yaml,products-api.yaml,orders-api.yaml \
  collection.json \
  \
  --verbose

# Output:
# Smart mapping: 12 primary matches, 5 secondary matches
# Users API: 85% coverage
# Products API: 92% coverage  
# Orders API: 78% coverage
# Overall Coverage: 85.00%

Example 20: Newman Reports with Smart Mapping

# Newman report analysis
swagger-coverage-cli api-spec.yaml newman-report.json \
  --newman \
  \
  --output smart-newman-report.html

# Output includes execution data:
# Smart mapping: 8 primary matches, 4 secondary matches
# Average response time: 125ms
# Coverage: 66.67%

Example 21: CSV API Specification

# Works with CSV format APIs
swagger-coverage-cli analytics-api.csv collection.json --smart-mapping

# Output:
# CSV format processed successfully
# Smart mapping: 3 primary matches, 1 secondary matches
# Coverage: 80.00%

Example 22: Performance Testing with Large APIs

# Handle large API specifications efficiently
swagger-coverage-cli large-api-spec.yaml large-collection.json \
  \
  --verbose

# Output:
# Extracted operations: 1000
# Processing time: 2.3 seconds
# Smart mapping: 750 primary matches, 150 secondary matches
# Coverage: 90.00%

Performance and Stress Testing

Smart mapping is designed to handle large-scale API specifications efficiently.

Example 23: Large Dataset Performance

Test Scenario:

API Operations: 1,000 endpoints with 2,000 status codes
Postman Requests: 100 test requests
Processing Time: < 5 seconds
Memory Usage: Optimized for large datasets

Performance Results:

Operations processed: 2,000
Requests analyzed: 100
Smart mapping time: 2.3 seconds
Memory usage: 45MB
Coverage: 85.00%

Performance: ✅ Excellent (under 5-second target)

Example 24: Complex Path Similarity Calculations

Stress Test:

// 1,000 iterations of complex path calculations
const testCases = [
  ['https://api.example.com/users/123', '/users/{id}'],
  ['https://api.example.com/organizations/org1/users/user1/permissions', 
   '/organizations/{orgId}/users/{userId}/permissions'],
  // ... 998 more complex cases
];

// Result: All calculations complete in < 1 second

Example 25: Multi-Status Code Scenarios

Complex Matching:

# API with extensive status code coverage
paths:
  /orders:
    post:
      responses:
        '201': { description: Created }
        '202': { description: Accepted }
        '400': { description: Bad Request }
        '401': { description: Unauthorized }
        '403': { description: Forbidden }
        '409': { description: Conflict }
        '422': { description: Unprocessable Entity }
        '500': { description: Server Error }
        '502': { description: Bad Gateway }
        '503': { description: Service Unavailable }

Smart Mapping Result:

Efficiently prioritizes success codes (201, 202)
Accurately matches tested error scenarios
Maintains high performance with complex operations

Best Practices

Recommendation 1: Enable Smart Mapping for Better Coverage

❌ Without Smart Mapping:

swagger-coverage-cli api-spec.yaml collection.json
# Result: 44.44% coverage (many false negatives)

✅ With Smart Mapping:

swagger-coverage-cli api-spec.yaml collection.json --smart-mapping
# Result: 50.00% coverage (improved accuracy)

Recommendation 2: Use Verbose Mode for Insights

swagger-coverage-cli api-spec.yaml collection.json --verbose

Benefits:

See smart mapping statistics
Understand primary vs secondary matches
Identify areas for test improvement

Recommendation 3: Combine with Strict Validation

swagger-coverage-cli api-spec.yaml collection.json \
  \
  --strict-query \
  --strict-body

Benefits:

Higher confidence in matches
Better validation of API contracts
More accurate coverage reporting

Recommendation 4: Multi-API Architecture Support

# Microservices
swagger-coverage-cli service1.yaml,service2.yaml,service3.yaml collection.json --smart-mapping

# API Gateway + Services
swagger-coverage-cli gateway.yaml,user-service.yaml,order-service.yaml collection.json --smart-mapping

Recommendation 5: Monitor Performance

For Large APIs:

Use --verbose to monitor processing time
Expected performance: < 5 seconds for 1000+ operations
Memory efficient for large datasets

Recommendation 6: HTML Report Analysis

swagger-coverage-cli api-spec.yaml collection.json \
  \
  --output detailed-smart-report.html

HTML Report Features:

Primary match indicators
📊 Confidence percentage badges
📈 Smart mapping statistics
🎯 Visual coverage improvements

Conclusion

Smart endpoint mapping significantly improves API coverage accuracy through:

Intelligent Status Code Prioritization: Focuses on success scenarios
Advanced Path Matching: Handles parameter variations gracefully
Confidence-Based Scoring: Provides match quality insights
Robust Error Handling: Graceful degradation for edge cases
Multi-API Support: Scales for microservices and complex architectures
Performance Optimization: Efficient processing for large datasets

Key Metrics:

38 comprehensive test cases across 8 categories
5.56 percentage point improvement in coverage accuracy
Sub-5-second performance for 1000+ operations
100% backward compatibility with existing functionality

Smart mapping is enabled by default for all operations to provide more accurate API coverage insights!

swagger-coverage-cli your-api-spec.yaml your-collection.json --verbose

FilesExpand file tree

smart-mapping-examples.md

Latest commit

History

smart-mapping-examples.md

File metadata and controls

Smart Endpoint Mapping - Complete Use Cases and Examples

Table of Contents

Quick Start

Status Code Priority Matching

Example 1: Basic Status Code Prioritization

Example 2: Multiple Success Codes

Path and Parameter Matching

Example 3: Different Parameter Names

Example 4: Complex Path Patterns

Example 5: Versioned API Paths

Confidence Scoring

Example 6: Confidence Score Calculation

Example 7: Confidence-Based Prioritization

Edge Cases and Error Handling

Example 8: Malformed URLs

Example 9: Missing Status Codes

Example 10: Empty Collections

Real-World API Scenarios

Example 11: RESTful CRUD Operations

Example 12: Mixed Success and Error Codes

Multi-API Support

Example 13: Microservices Architecture

Example 14: API Gateway Aggregation

Example 15: API Versioning Scenarios

CLI Integration Examples

Example 16: Basic Smart Mapping

Example 17: Verbose Smart Mapping

Example 18: Smart Mapping with Strict Validation

Example 19: Multi-API with Smart Mapping

Example 20: Newman Reports with Smart Mapping

Example 21: CSV API Specification

Example 22: Performance Testing with Large APIs

Performance and Stress Testing

Example 23: Large Dataset Performance

Example 24: Complex Path Similarity Calculations

Example 25: Multi-Status Code Scenarios

Best Practices

Recommendation 1: Enable Smart Mapping for Better Coverage

Recommendation 2: Use Verbose Mode for Insights

Recommendation 3: Combine with Strict Validation

Recommendation 4: Multi-API Architecture Support

Recommendation 5: Monitor Performance

Recommendation 6: HTML Report Analysis

Conclusion