x-openapi-flow-local-example

x-openapi-flow Local Example Project

This folder simulates a kickstart project with standard Swagger (OAS3) and Swagger UI.

Overview

This example is designed to demonstrate the expected workflow:

• Keep a base OpenAPI spec in the project root (swagger.json) without x-openapi-flow
• Generate a dedicated sidecar file with only library data via npx x-openapi-flow init
• Apply sidecar data into a full OpenAPI output via npx x-openapi-flow apply

Minimal Dependencies

• express (HTTP server for local Swagger UI)
• swagger-ui-express (Swagger UI integration)
• x-openapi-flow (local CLI package under test)

Project Files

• swagger.json: base OpenAPI (market-standard project root file)
• swagger.x.json: sidecar generated by init (library-only data)
• examples/swagger.x.yaml: complete sidecar example (all extension fields)
• examples/swagger.x.json: complete sidecar example (all extension fields)

Naming convention:

• {context}.x.yaml
• {context}.x.json

The example sidecars under examples/ intentionally cover all supported x-openapi-flow fields:

• required: version, id, current_state
• optional: description, idempotency.header, idempotency.required
• transitions: target_state, trigger_type, condition, next_operation_id, prerequisite_operation_ids, prerequisite_field_refs, propagated_field_refs

Setup

1) Install dependencies

cd example-project
npm install

2) Start Swagger UI

npm start

Open:

• http://localhost:3000/docs

By default, this server loads swagger.flow.json when it exists; otherwise it falls back to swagger.json. You can force a specific local file with SWAGGER_SPEC_FILE (example: SWAGGER_SPEC_FILE=swagger.json npm start).

3) Sidecar workflow

npm run init
# force recreate when swagger.flow.json already exists (non-interactive)
npx x-openapi-flow init --force
npm run diff
npm run apply
npm run apply:yaml-example
npm run apply:json-example
npm run validate
npm run lint
npm run graph
npm run doctor

Workflow summary:

• init: reads swagger.json and creates swagger.x.json sidecar by default.
• diff: previews sidecar drift (added/changed/removed operations) before writing outputs.
• apply: merges sidecar data into swagger.flow.json (keeps swagger.json clean).
• validate, lint, and graph: run on swagger.flow.json after apply.

Development Notes

• Dependency x-openapi-flow points to ../flow-spec.
• After making changes in the local CLI package, reinstall dependencies in this project to refresh the local link:

npm install