diff --git a/en/docs/develop/tools/integration-tools/connector-tool.md b/en/docs/develop/tools/integration-tools/connector-tool.md new file mode 100644 index 00000000000..1096000aae7 --- /dev/null +++ b/en/docs/develop/tools/integration-tools/connector-tool.md @@ -0,0 +1,122 @@ +--- +sidebar_position: 10 +title: Connector Tool +description: Generate production-ready Ballerina connectors from OpenAPI specifications using an AI-assisted pipeline. +--- + +# Connector Tool + +:::note Pre-Release +::: + +The `bal connector` tool automates the full lifecycle of building a Ballerina connector from an OpenAPI specification. It runs a five-stage pipeline (sanitizing the spec, generating and validating a typed client, creating tests and usage examples, and producing documentation) using Anthropic Claude to handle AI-assisted steps such as fixing compilation errors, generating realistic examples, and filling in missing operation identifiers. + +## Prerequisites + +Export your Anthropic API key as an environment variable: + +```bash +export ANTHROPIC_API_KEY= +``` + +## Generating a connector from an OpenAPI specification + +### Basic usage + +```bash +bal connector openapi -i ./openapi.yaml +``` + +This runs all five pipeline stages and writes the connector artifacts to the current directory. + +### Pipeline stages + +The tool runs the following stages in sequence: + +1. **Sanitize**: Flattens nested `$ref` chains, aligns naming with Ballerina conventions, AI-generates missing `operationId` values, and records every transformation in `docs/spec/sanitations.md`. +2. **Client**: Generates a typed Ballerina client from the sanitized spec. If the generated code has compilation errors, the tool attempts to fix them automatically using AI before re-validating. +3. **Tests**: Generates a mock-server test suite and a live-server test suite for the client. +4. **Examples**: AI-creates realistic, runnable usage examples for the connector. +5. **Docs**: Auto-generates a `README.md` for the connector package. + +### Skipping stages + +Use `-x` (repeatable) to skip one or more stages: + +```bash +# Fast iteration: generate only the sanitized spec and client +bal connector openapi -i ./openapi.yaml -x tests -x examples -x docs +``` + +### Interactive mode + +Pause after each stage to review the output before continuing: + +```bash +bal connector openapi -i ./openapi.yaml --interactive +``` + +## Updating a connector when the API changes + +When the upstream API publishes a new spec version, pass the new file and point `--spec-dir` at the directory containing the existing `sanitations.md`. The tool reapplies all recorded sanitations before running the pipeline, preserving naming and alignment fixes accumulated over prior runs. + +```bash +bal connector openapi -i ./openapi-v2.yaml -o ./my-connector --spec-dir ./my-connector/docs/spec +``` + +## Workflow examples + +**Full connector package from scratch** + +Run with defaults to get a complete package including client, tests, examples, and README: + +```bash +bal connector openapi -i stripe-openapi.yaml -o ./stripe-connector +``` + +**Filtered connector for a subset of the API** + +Use `--tags` or `--operations` to generate a connector for a specific slice of a large API: + +```bash +# Generate only endpoints tagged "payments" +bal connector openapi -i stripe-openapi.yaml -o ./stripe-payments --tags payments + +# Generate specific operations +bal connector openapi -i stripe-openapi.yaml -o ./stripe-minimal \ + --operations createPaymentIntent,retrievePaymentIntent +``` + +**Remote-method client** + +By default the generated client uses Ballerina resource methods. Use `--remote` to generate remote methods instead: + +```bash +bal connector openapi -i ./openapi.yaml --remote +``` + +## Command reference + +```bash +bal connector openapi -i [options] +``` + +| Flag | Alias | Required | Default | Description | +|------|-------|----------|---------|-------------| +| `--input` | `-i` | Yes | | Path to the OpenAPI specification file (YAML or JSON) | +| `--output` | `-o` | No | Current directory | Output directory for the generated connector | +| `--quiet` | `-q` | No | | Suppress all output except errors | +| `--verbose` | `-v` | No | | Show detailed diagnostic output for each stage | +| `--spec-dir` | | No | `./docs/spec` | Directory for the aligned spec and `sanitations.md` | +| `--example-dir` | | No | `./examples` | Output directory for generated examples | +| `--exclude` | `-x` | No | | Exclude a pipeline stage: `sanitize`, `client`, `tests`, `examples`, `docs` (repeatable) | +| `--license` | | No | | Path to a license header file to prepend to generated source files | +| `--tags` | `-t` | No | All tags | Filter generation to specific OpenAPI tags (repeatable) | +| `--operations` | | No | All operations | Generate only the specified operation IDs (repeatable) | +| `--remote` | | No | | Generate remote methods instead of resource methods | +| `--interactive` | | No | | Pause after each stage and prompt before continuing | + +## What's next + +- [OpenAPI Tool](openapi-tool.md): Generate Ballerina services and clients directly from OpenAPI specs without the full connector pipeline +- [gRPC Tool](grpc-tool.md): Generate gRPC services and clients from Protocol Buffer definitions diff --git a/en/docs/develop/tools/tools.md b/en/docs/develop/tools/tools.md index 1e4fff2c4ed..fc14b56db57 100644 --- a/en/docs/develop/tools/tools.md +++ b/en/docs/develop/tools/tools.md @@ -24,6 +24,7 @@ Generate Ballerina code from API specifications, protocol definitions, and domai - [EDI Tool](integration-tools/edi-tool.md) -- Generate Ballerina code from EDI schema definitions for B2B data exchange - [WSDL Tool](integration-tools/wsdl-tool.md) -- Generate clients for SOAP/WSDL web services - [XSD Tool](integration-tools/xsd-tool.md) -- Generate Ballerina record types from XML Schema definitions +- [Connector Tool](integration-tools/connector-tool.md) -- Generate production-ready Ballerina connectors from OpenAPI specifications using an AI-assisted pipeline ## Migration tools @@ -53,3 +54,4 @@ Migrate existing integrations from other platforms to WSO2 Integrator. | EDI | `bal edi` | EDI schema | EDI parser/generator | CLI only | | Scan | `bal scan` | Source code | Analysis report | CLI only | | Persist | `bal persist` | Record types | Data store client | CLI only | +| Connector | `bal connector` | OpenAPI YAML/JSON | Full connector package (client, tests, examples, docs) | CLI only | diff --git a/en/sidebars.ts b/en/sidebars.ts index 6478323bf8d..9e50552ebbe 100644 --- a/en/sidebars.ts +++ b/en/sidebars.ts @@ -329,6 +329,7 @@ const sidebars: SidebarsConfig = { 'develop/tools/integration-tools/wsdl-tool', 'develop/tools/integration-tools/xsd-tool', 'develop/tools/integration-tools/persist-tool', + 'develop/tools/integration-tools/connector-tool', ], }, {