openapi-format

openapi-format is a tool for formatting OpenAPI documents by ordering fields, applying casing rules, filtering elements, and applying overlays. It helps standardize OpenAPI specifications for public documentation, maintenance, and CI/CD pipelines.

Key Capabilities:

• Ordering: Sort OpenAPI fields hierarchically or alphabetically.
• Formatting: Apply casing (camelCase, PascalCase, etc.) and clean indentation for JSON/YAML.
• Filtering: Remove specific elements like internal endpoints, beta tags, or unused components based on methods, tags, or operationIDs.
• Transformation: Split large documents into multi-file structures, bundle references, or convert between OpenAPI versions (3.0/3.1 to 3.1/3.2).
• Customization: Use OpenAPI Overlays to extend or customize existing documents.

The textReplace option allows you to perform a global search and replace for text within the OpenAPI specification's description, summary, and url fields.

# Example: Replace specific terms
textReplace:
  - searchFor: 'Pets'
    replaceWith: 'Dogs'
  - searchFor: 'swagger.io'
    replaceWith: 'openapis.org'

Use operationIds to remove specific fields and attached fields that match the provided operationId values. Use inverseOperationIds to keep only the specified operation IDs.

# Example: Removing specific operationId
operationIds:
  - findPetsByStatus
  - updatePet

By default, openapi-format removes empty objects, except for those within examples, security, schemas, default, oneOf, or allOf.

• Set preserveEmptyObjects: true to keep all empty objects.
• Pass an array of keys (e.g., ['schema']) to only prevent removal of empty objects for those specific keys.

# Example: Only preserve empty objects if they are under the 'schema' key
preserveEmptyObjects:
  - schema

The stripFlags option removes the custom flag property itself from a field, but leaves the parent field and its other properties intact. This is different from flags, which removes the entire field containing the flag.

# Example: Remove the 'x-exclude' key but keep the rest of the operation
stripFlags:
  - x-exclude

Control which media types are present in your OpenAPI document:

• responseContent: Removes content from the Response Object that matches the specified media types.
• inverseResponseContent: Keeps only the specified media types in responses.
• requestContent: Removes content from the Request Body Object that matches the specified media types.
• inverseRequestContent: Keeps only the specified media types in request bodies.

# Example: Removing application/json from responses
responseContent:
  - application/json

The operations filter allows targeting specific combinations of HTTP methods and paths using the format METHOD::/path. This is useful when operationId is not available. It supports wildcards:

• Strict matching: "GET::/pets" targets only the GET method on /pets.
• Method wildcard: "*::/pets" targets all methods on /pets.
• Path wildcard: "GET::/pets/*" targets the GET method on /pets and any sub-paths (e.g., /pets/123).
• Full wildcard: "*::/pets/*" targets all methods on /pets and all sub-paths.

Note: Always put quotes around the target definition.

# Example: Target all methods on /pets and its sub-paths
operations:
  - "*::/pets/*"

Use methods to remove all fields and attached fields that match the specified HTTP verbs. Use inverseMethods to keep only the specified verbs and remove all others.

# Example: Removing get, put, and post
methods:
  - get
  - put
  - post

Custom properties (flags) can be used to filter the document:

• flags: Removes all fields matching the specified custom property names (e.g., x-exclude).
• inverseFlags: An aggressive option that keeps only path operations, tags, and x-tagGroups that match the flags. It keeps components by default.
• flagValues: Removes fields matching a specific flag name AND value (e.g., x-version: 1.0). This also works for flags containing arrays of values.
• inverseFlagValues: An aggressive option that keeps only items matching the specified flag/value combination. Like inverseFlags, it keeps components (use unusedComponents to clean those up).

# Example: Removing specific flag values
flagValues:
  - x-version: 1.0
  - x-version: 3.0

# Example: Removing a flag entirely
flags:
  - x-exclude

When running the CLI, transformations are applied in a strict, deterministic sequence. Understanding this order is critical when configuring multiple overlapping features (e.g., filtering before or after casing).

Pipeline Order:

1. generate (Operation ID generation)
2. filter (Removing elements)
3. overlay (Applying overlay actions)
4. sort (Ordering fields/components)
5. casing (Applying casing rules)
6. convertTo (Version conversion)
7. rename (Renaming info.title)
8. Write Output (Writing to file/split or printing to stdout)