adp-api-transformer

adp-api-transformer

A CLI tool that transforms OpenAPI specifications (JSON or YAML) for use in the ADP1 APIM repository. It enriches specs with missing attributes, normalizes operation metadata, and can split large specs into smaller per-tag or per-path files — each containing only the relevant paths and schemas.

Table of Contents

• Features
• Installation
• Usage
  • Basic conversion
  • Split by tag
  • Split by path
• What the tool does
  • Attribute enrichment
  • Schema filtering
  • Path rewriting
• Examples
• Requirements
• Building and publishing

Features

• Accepts OpenAPI specs in .json, .yaml, or .yml formats.
• Adds missing operationId, summary, and tags fields to every operation.
• Ensures every operationId ends with the -{{consumerphase}} suffix (appends it if missing).
• Sets info.title to the template value {{apiTitle}}.
• Split by tag — produces one file per tag, with paths starting after the tag segment.
• Split by path — groups endpoints by their first path segment, with an optional prefix to ignore (e.g. api/v1).
• Only includes schemas that are actually referenced by each split file (plus general shared schemas), resolved recursively.
• Outputs all specs as formatted JSON.

Installation

From PyPI

pip install adp-api-transformer

For development

Clone the repository and install in editable mode:

git clone <repo-url>
cd adp-api-converter
pip install -e .

Usage

adp-api-transformer <input_file> [output] [--split-by-tag] [--split-by-path] [--ignore-prefix PREFIX]

When using --split-by-tag or --split-by-path, output files are written to a directory named after the input file (without the extension).

---

Basic conversion

Convert a spec and write a single enriched JSON file:

adp-api-transformer api.yaml modified_api.json

Split by tag

Create one file per tag. Each file only contains the operations for that tag, with paths rewritten to start after the tag segment:

adp-api-transformer api.yaml --split-by-tag

Given an input with paths /collection, /collection/{id}, and /user/profile, this produces:

api/
  collection.openapi.json   # paths: /  and /{id}
  user.openapi.json          # paths: /profile

Split by path

Group endpoints by the first meaningful path segment. Useful when tags are absent or unreliable:

adp-api-transformer api.yaml --split-by-path

If your paths share a common prefix (e.g. /api/v1/studies/..., /api/v1/extractions/...), use --ignore-prefix so grouping happens on the segment after the prefix:

adp-api-transformer api.yaml --split-by-path --ignore-prefix api/v1

This groups /api/v1/studies/{id} under studies (path becomes /{id}) and /api/v1/extractions under extractions (path becomes /).

What the tool does

Attribute enrichment

Every operation in the spec is processed with the following rules:

Schema filtering

When splitting, each output file only includes:

1. Directly referenced schemas — any $ref pointing to #/components/schemas/... found in that file's operations.
2. Transitively referenced schemas — if schema A references schema B, both are included.
3. General shared schemas — schemas named security, error, paginated, or metadata are always included (if they exist).
4. Other component types — securitySchemes are copied to every output file. Other top-level fields (e.g. servers, security) are also preserved.

Path rewriting

Examples

The example/ directory contains sample output files generated by splitting the included example.openapi.json by tag:

example/
  collection.openapi.json
  domain.openapi.json
  user.openapi.json
  workflow.openapi.json
  ...

To regenerate them:

adp-api-transformer example.openapi.json --split-by-tag

Requirements

• Python 3.9+
• pyyaml