API Changelog Plugin

A Backstage plugin for comparing Swagger/OpenAPI specifications and visualizing API changes with detailed diff information.

Features

• 🔍 Comprehensive API Comparison: Compare two Swagger/OpenAPI specs and detect all changes
• 📊 Visual Diff Viewer: React component with Material-UI v4 to display changes
• 🎯 Detailed Analysis: Extracts nested property changes, parameter modifications, and schema differences
• ✅ False Positive Filtering: Automatically filters out array reordering artifacts
• 📦 Library Function: Programmatic API for use in other applications

Installation

yarn add @patelmohit719/plugin-api-changelog

Usage

React Component

Display API changes in your React application:

import { SwaggerDiffViewer } from '@patelmohit719/plugin-api-changelog';

// Option 1: Load from file path
<SwaggerDiffViewer diffFilePath="/diff.json" />

// Option 2: Pass data directly
<SwaggerDiffViewer diffData={diffData} />

Comparison Function

Compare Swagger specs programmatically:

import { compareSwaggerSpecs } from '@patelmohit719/plugin-api-changelog';

const oldSpec = {
  paths: {
    '/api/users': {
      get: {
        responses: {
          '200': {
            schema: {
              type: 'object',
              properties: {
                name: { type: 'string' }
              }
            }
          }
        }
      }
    }
  }
};

const newSpec = {
  paths: {
    '/api/users': {
      get: {
        responses: {
          '200': {
            schema: {
              type: 'object',
              properties: {
                name: { type: 'string' },
                email: { type: 'string' }  // Added property
              }
            }
          }
        }
      }
    }
  }
};

const diffResult = compareSwaggerSpecs(oldSpec, newSpec);

console.log(diffResult.summary);
// {
//   endpointsAdded: 0,
//   endpointsRemoved: 0,
//   endpointsModified: 1,
//   schemasAdded: 0,
//   schemasRemoved: 0,
//   schemasModified: 0
// }

API Reference

compareSwaggerSpecs(oldSpec, newSpec)

Compares two Swagger/OpenAPI specification objects and returns detailed diff information.

Parameters:

• oldSpec (object): The old Swagger/OpenAPI specification object
• newSpec (object): The new Swagger/OpenAPI specification object

Returns: DetailedDiffResult

interface DetailedDiffResult {
  summary: {
    endpointsAdded: number;
    endpointsRemoved: number;
    endpointsModified: number;
    schemasAdded: number;
    schemasRemoved: number;
    schemasModified: number;
  };
  endpoints: EndpointChange[];
  schemas: SchemaChange[];
}

interface EndpointChange {
  method: string;              // GET, POST, PUT, etc.
  endpoint: string;            // /api/users
  changeType: 'added' | 'modified' | 'removed';
  parameterChanges?: ParameterChange[];
  responseChanges?: ResponseChange[];
  requestBodyChanges?: PropertyChange[];
}

interface ResponseChange {
  statusCode: string;          // 200, 201, etc.
  contentType: string;         // application/json
  propertyChanges: PropertyChange[];
}

interface PropertyChange {
  property: string;            // results.items.rfp.contract.service_categories
  changeType: 'added' | 'modified' | 'removed';
  oldValue?: any;
  newValue?: any;
  description?: string;
}

SwaggerDiffViewer

React component to visualize API changes.

Props:

• diffFilePath?: string - Path to diff JSON file (default: 'diff.json')
• diffData?: SwaggerDiffData - Direct diff data object (takes precedence over diffFilePath)

Example Output

The comparison function returns structured data showing:

• Endpoints: Added, removed, or modified endpoints with:

  • Parameter changes (query, path, body, header)
  • Request body changes
  • Response changes with nested property paths

• Schemas: Added, removed, or modified schema definitions with property-level changes

• Property Paths: Formatted for readability (e.g., results (array) -> items (object) -> rfp (object) -> contract (object) -> service_categories (array))

Features

• ✅ Handles Swagger 2.0 and OpenAPI 3.0
• ✅ Resolves $ref references recursively
• ✅ Filters false positives (array reordering artifacts)
• ✅ Extracts nested property changes
• ✅ Supports all HTTP methods (GET, POST, PUT, PATCH, DELETE, etc.)
• ✅ Sorted output for consistent results

License

Apache-2.0