npm package: @lxgicstudios/api-changelog
Description: Compare two OpenAPI/Swagger spec files and generate a human-readable changelog. Detect added, removed, and changed endpoints, new required fields, deprecations, and breaking changes.
Author: LXGIC Studios
Latest version: 1.0.0

# @lxgicstudios/api-changelog

[![npm version](https://img.shields.io/npm/v/@lxgicstudios/api-changelog)](https://www.npmjs.com/package/@lxgicstudios/api-changelog)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![Node.js](https://img.shields.io/badge/node-%3E%3D18-brightgreen)](https://nodejs.org)
[![Zero Dependencies](https://img.shields.io/badge/dependencies-0-blue)](https://www.npmjs.com/package/@lxgicstudios/api-changelog)

Compare two OpenAPI or Swagger spec files and generate a human-readable changelog. Spot added endpoints, removed routes, changed parameters, new required fields, and deprecations at a glance.

**Zero external dependencies.** Parses both JSON and YAML specs using a built-in parser.

## Install

```bash
npm install -g @lxgicstudios/api-changelog
```

Or run directly:

```bash
npx @lxgicstudios/api-changelog v1.json v2.json
```

## Usage

### Compare two specs

```bash
api-changelog old-spec.json new-spec.json
```

### Generate Markdown changelog

```bash
api-changelog v1.yaml v2.yaml --format markdown > CHANGELOG.md
```

### Show only breaking changes

```bash
api-changelog v1.json v2.json --breaking-only
```

### JSON output

```bash
api-changelog v1.json v2.json --json
```

## Features

- Compare OpenAPI 3.x and Swagger 2.x specs
- JSON and YAML spec support (built-in parser, no deps)
- Detect added and removed endpoints
- Detect changed parameters (added, removed, required changes)
- Detect type changes in parameters
- Detect response code additions and removals
- Detect deprecations and un-deprecations
- Flag breaking vs non-breaking changes
- Markdown output for release notes
- JSON output for automation
- Breaking-only filter for CI/CD gates
- Version tracking between specs
- Colorful terminal output
- Exit code 1 when breaking changes are found

## Detected Changes

| Change | Breaking? |
|--------|-----------|
| Endpoint removed | Yes |
| Required parameter added | Yes |
| Parameter removed | Yes |
| Parameter type changed | Yes |
| Response code removed | Yes |
| Parameter made required | Yes |
| Endpoint added | No |
| Optional parameter added | No |
| Response code added | No |
| Endpoint deprecated | No |
| Summary/description updated | No |
| Parameter made optional | No |

## Options

| Option | Alias | Description | Default |
|--------|-------|-------------|---------|
| `--help` | `-h` | Show help message | |
| `--json` | | Output results as JSON | `false` |
| `--format <type>` | `-f` | Output format: text or markdown | `text` |
| `--breaking-only` | `-b` | Show only breaking changes | `false` |
| `--no-color` | | Disable colored output | `false` |

## Exit Codes

| Code | Meaning |
|------|---------|
| `0` | No breaking changes |
| `1` | Breaking changes found |

## Output Formats

### Text (default)
Colorful terminal output with clear categorization and summary.

### Markdown
Clean Markdown with emoji indicators. Perfect for piping into a `CHANGELOG.md` or PR description.

### JSON
Full structured output for automation, CI/CD pipelines, and custom tooling.

---

**Built by [LXGIC Studios](https://lxgicstudios.com)**

[GitHub](https://github.com/lxgicstudios/api-changelog) | [Twitter](https://x.com/lxgicstudios)