npm package: @patelmohit719/plugin-api-changelog
Description: A Backstage plugin for comparing Swagger/OpenAPI specifications and visualizing API changes with detailed diff information.
Latest version: 0.1.9

# 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

```bash
yarn add @patelmohit719/plugin-api-changelog
```

## Usage

### React Component

Display API changes in your React application:

```tsx
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:

```tsx
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`

```typescript
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