OpenAPI Changes

https://pb33f.io/openapi-changes/
Admin
OpenAPI Changes is a tool designed to detect breaking changes and diff OpenAPI specifications in a...
Tokens:7,456
Snippets:72
Trust Score:7.5
Update:9 months ago
Show doc for...
Tokens:
Raw
### Full example with multiple overrides (Production API rules)

Source: https://pb33f.io/openapi-changes/configuring

A comprehensive example combining several common overrides for a production API, including deprecation, flexible enum handling, and strict parameter rules.

```APIDOC
## POST /changes-rules.yaml

### Description
Sets production API rules, including non-breaking operation removals, flexible enum handling, and strict security requirement changes.

### Method
POST

### Endpoint
/changes-rules.yaml

### Parameters
#### Request Body
- **pathItem** (object) - Optional - Rules related to path item changes.
  - **get** (object) - Optional - Rules for GET operations.
    - **removed** (boolean) - Optional - If false, removing GET operations is not breaking.
  - **post** (object) - Optional - Rules for POST operations.
    - **removed** (boolean) - Optional - If false, removing POST operations is not breaking.
  - **put** (object) - Optional - Rules for PUT operations.
    - **removed** (boolean) - Optional - If false, removing PUT operations is not breaking.
  - **delete** (object) - Optional - Rules for DELETE operations.
    - **removed** (boolean) - Optional - If false, removing DELETE operations is not breaking.
  - **patch** (object) - Optional - Rules for PATCH operations.
    - **removed** (boolean) - Optional - If false, removing PATCH operations is not breaking.
- **schema** (object) - Optional - Rules related to schema changes.
  - **enum** (object) - Optional - Rules for enum changes within schemas.
    - **added** (boolean) - Optional - If false, adding new enum values is not flagged as breaking.
    - **removed** (boolean) - Optional - If false, removing enum values is acceptable.
- **securityRequirement** (object) - Optional - Rules for security requirement changes.
  - **schemes** (object) - Optional - Rules for changes in security schemes.
    - **added** (boolean) - Optional - If true, adding new security schemes is breaking.
    - **removed** (boolean) - Optional - If true, removing security schemes is breaking.
  - **scopes** (object) - Optional - Rules for changes in security scopes.
    - **added** (boolean) - Optional - If true, adding new security scopes is breaking.
    - **removed** (boolean) - Optional - If true, removing security scopes is breaking.

### Request Example
```yaml
pathItem:
  get:
    removed: false
  post:
    removed: false
  put:
    removed: false
  delete:
    removed: false
  patch:
    removed: false
schema:
  enum:
    added: false
    removed: false
securityRequirement:
  schemes:
    added: true
    removed: true
  scopes:
    added: true
    removed: true
```

### Response
#### Success Response (200)
- **message** (string) - Confirmation message.

#### Response Example
```json
{
  "message": "Configuration applied successfully."
}
```
```

--------------------------------

### Strict Mode for New APIs (YAML)

Source: https://pb33f.io/openapi-changes/configuring

Enables stricter checking for new APIs, flagging changes in descriptions, examples, summaries, and operation descriptions as breaking. This helps ensure stability and encourages careful review of initial API definitions.

```yaml
# changes-rules.yaml - Strict mode for new APIs
schema:
  description:
    modified: true  # Even description changes should be reviewed
  example:
    modified: true  # Example changes could affect consumer tests

operation:
  summary:
    modified: true  # Summary changes need review
  description:
    modified: true  # Description changes need review

```

--------------------------------

### Production API Rules Example (YAML)

Source: https://pb33f.io/openapi-changes/configuring

A comprehensive configuration for production APIs, combining relaxed rules for deprecation workflows, flexible enum handling, and strict rules for security changes. It demonstrates how to override default behaviors for specific API aspects.

```yaml
# changes-rules.yaml - Production API rules
#
# These rules are tailored for a mature API with:
# - Deprecation workflows (removals are expected)
# - Flexible enum handling (consumers handle unknowns)
# - Strict parameter rules (parameters are contracted)

# Operation/endpoint removals are expected (deprecation workflow)
pathItem:
  get:
    removed: false
  post:
    removed: false
  put:
    removed: false
  delete:
    removed: false
  patch:
    removed: false

# Enum handling - consumers should handle unknown values
schema:
  enum:
    added: false
    removed: false

# Security changes should always be flagged
securityRequirement:
  schemes:
    added: true
    removed: true
  scopes:
    added: true
    removed: true

```

--------------------------------

### Customizing Output with Command Flags

Source: https://pb33f.io/openapi-changes/command-arguments

Customize the output of `openapi-changes` using various command flags. These flags control color output, limit results, and specify base paths or configuration files.

```bash
openapi-changes console -t ./ sample-specs/petstorev3.json
```

--------------------------------

### Using GitHub Repository History

Source: https://pb33f.io/openapi-changes/command-arguments

Reference an OpenAPI spec hosted on GitHub by providing the direct URL to the spec file. The tool will fetch and analyze the history from the specified GitHub URL.

```bash
openapi-changes console \
https://github.com/OAI/OpenAPI-Specification/blob/main/examples/v3.0/petstore.yaml openapi-changes console \
https://github.com/stripe/openapi/blob/master/openapi/spec3.json
```

--------------------------------

### Comparing Left and Right OpenAPI Files

Source: https://pb33f.io/openapi-changes/command-arguments

Compare two OpenAPI specification files directly by providing paths to both the original ('left') and modified ('right') files. This mode simulates a single commit history for comparison purposes.

```bash
openapi-changes console old-spec.json new-spec.json openapi-changes console \
/home/pb33f/corp-code/old-spec.json /home/pb33f/corp-code/new-spec.json
```

--------------------------------

### Generate HTML Report with OpenAPI Changes

Source: https://pb33f.io/openapi-changes/html-report

Generates an HTML report visualizing differences in OpenAPI specifications. It takes the path to the specification file as input and outputs an HTML file. The report file name can be customized using the `--report-file` flag.

```bash
openapi-changes html-report ./sample-specs/petstorev3.json && open report.html
```

```bash
openapi-changes html-report --report-file custom_report.html ./sample-specs/petstorev3.json
```

--------------------------------

### Strict mode for new APIs

Source: https://pb33f.io/openapi-changes/configuring

Applies stricter rules for new APIs, flagging more changes as breaking to ensure stability.

```APIDOC
## POST /changes-rules.yaml

### Description
Applies strict rules for new APIs, flagging changes in descriptions, examples, summaries, and operation descriptions as breaking.

### Method
POST

### Endpoint
/changes-rules.yaml

### Parameters
#### Request Body
- **schema** (object) - Optional - Rules related to schema changes.
  - **description** (object) - Optional - Rules for schema description changes.
    - **modified** (boolean) - Optional - If true, schema description modifications are breaking.
  - **example** (object) - Optional - Rules for schema example changes.
    - **modified** (boolean) - Optional - If true, schema example modifications are breaking.
- **operation** (object) - Optional - Rules related to operation changes.
  - **summary** (object) - Optional - Rules for operation summary changes.
    - **modified** (boolean) - Optional - If true, operation summary modifications are breaking.
  - **description** (object) - Optional - Rules for operation description changes.
    - **modified** (boolean) - Optional - If true, operation description modifications are breaking.

### Request Example
```yaml
schema:
  description:
    modified: true
  example:
    modified: true
operation:
  summary:
    modified: true
  description:
    modified: true
```

### Response
#### Success Response (200)
- **message** (string) - Confirmation message.

#### Response Example
```json
{
  "message": "Configuration applied successfully."
}
```
```

--------------------------------

### Running OpenAPI Changes Console Command

Source: https://pb33f.io/openapi-changes/console

This command allows you to explore differences in OpenAPI specifications using an interactive terminal UI. It takes the path to your OpenAPI specification file as an argument. The console provides keyboard controls for navigation and viewing changes.

```bash
openapi-changes console ./sample-specs/petstorev3.json
```

--------------------------------

### Using Local Git Repository History

Source: https://pb33f.io/openapi-changes/command-arguments

Specify an OpenAPI spec within a local git repository by providing the path to the repository and the path to the spec file within it. This allows tracking changes through the git history.

```bash
openapi-changes console ./ specs/v3/openapi.yamlopenapi-changes console \
/home/pb33f/corp-code specs/v3/openapi.yaml
```

--------------------------------

### Handling Unresolved References with Base Path

Source: https://pb33f.io/openapi-changes/command-arguments

Use the `-p` or `--base` flag to specify a base URL or working directory when dealing with OpenAPI specs that contain unresolved external or remote references (`$ref`). This helps the tool resolve relative paths correctly.

```bash
openapi-changes console -p . sample-specs/petstorev3.json openapi-changes console -p https://somewhere.megacorp.com sample-specs/petstorev3.json
```

--------------------------------

### Relaxed mode for deprecation workflows

Source: https://pb33f.io/openapi-changes/configuring

Configures operation and path removals to be non-breaking, suitable for deprecation workflows where consumers have been warned.

```APIDOC
## POST /changes-rules.yaml

### Description
Configures rules to make operation and path removals non-breaking for deprecation workflows.

### Method
POST

### Endpoint
/changes-rules.yaml

### Parameters
#### Request Body
- **pathItem** (object) - Optional - Rules related to path item changes.
  - **get** (object) - Optional - Rules for GET operations.
    - **removed** (boolean) - Optional - If false, removing GET operations is not breaking.
  - **post** (object) - Optional - Rules for POST operations.
    - **removed** (boolean) - Optional - If false, removing POST operations is not breaking.
  - **put** (object) - Optional - Rules for PUT operations.
    - **removed** (boolean) - Optional - If false, removing PUT operations is not breaking.
  - **delete** (object) - Optional - Rules for DELETE operations.
    - **removed** (boolean) - Optional - If false, removing DELETE operations is not breaking.
  - **patch** (object) - Optional - Rules for PATCH operations.
    - **removed** (boolean) - Optional - If false, removing PATCH operations is not breaking.
  - **options** (object) - Optional - Rules for OPTIONS operations.
    - **removed** (boolean) - Optional - If false, removing OPTIONS operations is not breaking.
  - **head** (object) - Optional - Rules for HEAD operations.
    - **removed** (boolean) - Optional - If false, removing HEAD operations is not breaking.
  - **trace** (object) - Optional - Rules for TRACE operations.
    - **removed** (boolean) - Optional - If false, removing TRACE operations is not breaking.

### Request Example
```yaml
pathItem:
  get:
    removed: false
  post:
    removed: false
  put:
    removed: false
  delete:
    removed: false
  patch:
    removed: false
  options:
    removed: false
  head:
    removed: false
  trace:
    removed: false
```

### Response
#### Success Response (200)
- **message** (string) - Confirmation message.

#### Response Example
```json
{
  "message": "Configuration applied successfully."
}
```
```

--------------------------------

### Flexible enum handling

Source: https://pb33f.io/openapi-changes/configuring

Configures enum handling rules to allow adding new enum values safely and consider removing enum values acceptable.

```APIDOC
## POST /changes-rules.yaml

### Description
Configures rules for enum changes, making additions safe and removals acceptable.

### Method
POST

### Endpoint
/changes-rules.yaml

### Parameters
#### Request Body
- **schema** (object) - Optional - Rules related to schema changes.
  - **enum** (object) - Optional - Rules for enum changes within schemas.
    - **added** (boolean) - Optional - If false, adding new enum values is not flagged as breaking.
    - **removed** (boolean) - Optional - If false, removing enum values is acceptable.
    - **modified** (boolean) - Optional - If false, reordering enum values is acceptable.

### Request Example
```yaml
schema:
  enum:
    added: false
    removed: false
    modified: false
```

### Response
#### Success Response (200)
- **message** (string) - Confirmation message.

#### Response Example
```json
{
  "message": "Configuration applied successfully."
}
```
```

--------------------------------

### Flexible Response Code Handling (YAML)

Source: https://pb33f.io/openapi-changes/configuring

Allows for changes in response codes (adding or removing) to be considered non-breaking. This is useful for APIs that are undergoing cleanup of unused response codes or have flexible error handling mechanisms.

```yaml
# changes-rules.yaml - Flexible response codes
responses:
  codes:
    removed: false  # Removing response codes is acceptable
    added: false    # Adding new response codes is safe

```

--------------------------------

### Relaxed Mode for Deprecation Workflows (YAML)

Source: https://pb33f.io/openapi-changes/configuring

Configures openapi-changes to treat path item removals as non-breaking, suitable for deprecation workflows where consumers are expected to be warned in advance. This applies to all HTTP methods within a path item.

```yaml
# changes-rules.yaml - Relaxed rules for deprecation workflows
pathItem:
  get:
    removed: false
  post:
    removed: false
  put:
    removed: false
  delete:
    removed: false
  patch:
    removed: false
  options:
    removed: false
  head:
    removed: false
  trace:
    removed: false

```

--------------------------------

### Ignoring optional parameter changes

Source: https://pb33f.io/openapi-changes/configuring

Configures rules to make adding new optional parameters non-breaking, assuming consumers handle them gracefully.

```APIDOC
## POST /changes-rules.yaml

### Description
Configures rules to consider changes in parameter required status and schema required status as non-breaking.

### Method
POST

### Endpoint
/changes-rules.yaml

### Parameters
#### Request Body
- **parameter** (object) - Optional - Rules related to parameter changes.
  - **required** (object) - Optional - Rules for changes in parameter's required status.
    - **modified** (boolean) - Optional - If false, changing a parameter's required status is acceptable.
- **schema** (object) - Optional - Rules related to schema changes.
  - **required** (object) - Optional - Rules for changes in schema's required status.
    - **modified** (boolean) - Optional - If false, changing a schema's required status is acceptable.

### Request Example
```yaml
parameter:
  required:
    modified: false
schema:
  required:
    modified: false
```

### Response
#### Success Response (200)
- **message** (string) - Confirmation message.

#### Response Example
```json
{
  "message": "Configuration applied successfully."
}
```
```

--------------------------------

### Flexible Enum Handling (YAML)

Source: https://pb33f.io/openapi-changes/configuring

Sets rules for enum changes in schema definitions to be non-breaking. Adding new enum values is considered safe, and removing existing values is acceptable, assuming consumers can handle unknown values.

```yaml
# changes-rules.yaml - Flexible enum handling
schema:
  enum:
    added: false    # Adding new enum values is safe
    removed: false  # Removing enum values is acceptable
    modified: false # Reordering enum values is fine

```

--------------------------------

### Ignoring Optional Parameter Changes (YAML)

Source: https://pb33f.io/openapi-changes/configuring

Configures openapi-changes to consider changes in the 'required' status of parameters and schema properties as non-breaking. This is useful when API consumers are expected to handle optional parameters gracefully.

```yaml
# changes-rules.yaml - Flexible optional parameters
parameter:
  required:
    modified: false  # Changing required status is acceptable

schema:
  required:
    modified: false  # Schema required changes are acceptable

```

--------------------------------

### Flexible response code handling

Source: https://pb33f.io/openapi-changes/configuring

Configures rules to make removing response codes from an operation non-breaking.

```APIDOC
## POST /changes-rules.yaml

### Description
Configures rules to allow removing and adding response codes from operations as non-breaking changes.

### Method
POST

### Endpoint
/changes-rules.yaml

### Parameters
#### Request Body
- **responses** (object) - Optional - Rules related to response object changes.
  - **codes** (object) - Optional - Rules for individual response codes.
    - **removed** (boolean) - Optional - If false, removing response codes is acceptable.
    - **added** (boolean) - Optional - If false, adding new response codes is safe.

### Request Example
```yaml
responses:
  codes:
    removed: false
    added: false
```

### Response
#### Success Response (200)
- **message** (string) - Confirmation message.

#### Response Example
```json
{
  "message": "Configuration applied successfully."
}
```
```
Tokens:
Raw