{"id":49531625,"url":"https://github.com/algorandfoundation/algokit-oas-generator","last_synced_at":"2026-05-02T08:11:42.236Z","repository":{"id":321671187,"uuid":"1086665092","full_name":"algorandfoundation/algokit-oas-generator","owner":"algorandfoundation","description":null,"archived":false,"fork":false,"pushed_at":"2025-12-30T05:25:27.000Z","size":12141,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-01-02T16:06:38.306Z","etag":null,"topics":["algokit","utils"],"latest_commit_sha":null,"homepage":"","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/algorandfoundation.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-10-30T18:17:06.000Z","updated_at":"2025-12-30T05:25:27.000Z","dependencies_parsed_at":"2025-10-30T23:22:40.861Z","dependency_job_id":null,"html_url":"https://github.com/algorandfoundation/algokit-oas-generator","commit_stats":null,"previous_names":["algorandfoundation/algokit-configs","algorandfoundation/algokit-oas-generator"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/algorandfoundation/algokit-oas-generator","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/algorandfoundation%2Falgokit-oas-generator","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/algorandfoundation%2Falgokit-oas-generator/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/algorandfoundation%2Falgokit-oas-generator/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/algorandfoundation%2Falgokit-oas-generator/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/algorandfoundation","download_url":"https://codeload.github.com/algorandfoundation/algokit-oas-generator/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/algorandfoundation%2Falgokit-oas-generator/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":32527189,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-02T01:12:54.858Z","status":"online","status_checked_at":"2026-05-02T02:00:05.923Z","response_time":132,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["algokit","utils"],"created_at":"2026-05-02T08:11:41.440Z","updated_at":"2026-05-02T08:11:42.225Z","avatar_url":"https://github.com/algorandfoundation.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Algorand OpenAPI Converter\n\nA standalone tool for converting Algorand API specifications from OpenAPI 2.0 (Swagger) to OpenAPI 3.0 with Algorand-specific transformations and enhancements.\n\nThis converter fetches the latest OpenAPI specifications from the official Algorand repositories (go-algorand and indexer) and produces clean, validated OpenAPI 3.0 specifications ready for code generation in any language.\n\n## Features\n\n- **Automatic Fetching**: Downloads latest specs directly from Algorand GitHub repositories\n- **Format Conversion**: Converts Swagger 2.0 → OpenAPI 3.0 using swagger-converter\n- **Algorand Extensions**: Adds vendor extensions for Algorand-specific types:\n  - `x-algokit-bigint`: Marks 64-bit integer fields\n  - `x-algokit-signed-txn`: Identifies SignedTransaction fields\n  - `x-algokit-bytes-base64`: Identifies as field as explicitly base64. This is used denote a msgpack field that is explicitly a base64 bytes string.\n- **Validation \u0026 Fixes**: Automatically fixes known issues in source specs\n- **Msgpack Support**: Marks endpoints and fields that use msgpack encoding\n- **Field Transformations**: Applies required field corrections and naming fixes\n\n## Prerequisites\n\n- [Node.js 18+](https://nodejs.org/) - JavaScript runtime\n- [npm](https://www.npmjs.com/) - Package manager (included with Node.js)\n\n## Setup\n\n```bash\n# Install dependencies\nnpm install\n```\n\n## Usage\n\n### Convert All Specs\n\nConvert all three Algorand API specifications (Algod, Indexer, KMD):\n\n```bash\nnpm run convert-openapi\n```\n\n### Convert Individual Specs\n\nConvert specific API specifications:\n\n```bash\n# Convert only Algod spec\nnpm run convert-algod\n\n# Convert only Indexer spec\nnpm run convert-indexer\n\n# Convert only KMD spec\nnpm run convert-kmd\n```\n\n### Output\n\nThe converted OpenAPI 3.0 specifications will be written to:\n\n- `specs/algod.oas3.json` - Algod API specification\n- `specs/indexer.oas3.json` - Indexer API specification\n- `specs/kmd.oas3.json` - KMD API specification\n\n## How It Works\n\nThe converter processes API specifications through a five-stage pipeline:\n\n```mermaid\nflowchart TD\n    Start([User Command]) --\u003e Parse[Parse CLI Args]\n    Parse --\u003e FetchVersion{Fetch Latest\u003cbr/\u003eVersion?}\n\n    FetchVersion --\u003e|Yes| GitHub[Query GitHub API]\n    FetchVersion --\u003e|No| Version[Use Default]\n    GitHub --\u003e Version\n\n    Version --\u003e SelectAPI{Select API}\n    SelectAPI --\u003e|Algod| ConfigA[Load Algod Config]\n    SelectAPI --\u003e|Indexer| ConfigI[Load Indexer Config]\n    SelectAPI --\u003e|KMD| ConfigK[Load KMD Config]\n\n    ConfigA --\u003e Process[Process Pipeline]\n    ConfigI --\u003e Process\n    ConfigK --\u003e Process\n\n    Process --\u003e Fetch[1. Fetch Spec]\n    Fetch --\u003e Convert[2. Convert OAS2→OAS3]\n    Convert --\u003e Transform[3. Apply Transformations]\n    Transform --\u003e Validate[4. Validate]\n    Validate --\u003e Write[5. Write Output]\n    Write --\u003e End([Enhanced Spec])\n\n    style Start fill:#e1f5ff\n    style Process fill:#fff4e1\n    style Transform fill:#ffe1f5\n    style End fill:#e1ffe1\n```\n\n**Process Overview:**\n\n1. **Fetch**: Downloads the latest specification from Algorand's GitHub repository\n2. **Convert**: Transforms Swagger 2.0 to OpenAPI 3.0 format using swagger-converter\n3. **Transform**: Applies Algorand-specific enhancements (vendor extensions, field fixes, etc.)\n4. **Validate**: Ensures the output is a valid OpenAPI 3.0 specification\n5. **Output**: Writes the enhanced specification to the `specs/` directory\n\n## Source Specifications\n\n### Algod\n\n- **Source**: [go-algorand](https://github.com/algorand/go-algorand/blob/master/daemon/algod/api/algod.oas2.json)\n- **Format**: OpenAPI 2.0 (Swagger)\n- **Description**: Algorand node daemon API for interacting with the blockchain\n\n### Indexer\n\n- **Source**: [indexer](https://github.com/algorand/indexer/blob/master/api/indexer.oas2.json)\n- **Format**: OpenAPI 2.0 (Swagger)\n- **Description**: Algorand Indexer API for blockchain data queries\n\n### KMD\n\n- **Source**: [go-algorand](https://github.com/algorand/go-algorand/blob/master/daemon/kmd/api/swagger.json)\n- **Format**: Swagger 2.0\n- **Description**: Key Management Daemon API for managing signing keys\n\n## Algorand-Specific Transformations\n\nThe converter applies several transformations to make the specs more suitable for code generation. Transformations are applied sequentially in the following order:\n\n```mermaid\nflowchart LR\n    Input[OpenAPI 3.0 Spec] --\u003e T1[Fix Descriptions]\n    T1 --\u003e T2[Fix Known Bugs]\n    T2 --\u003e T3[Add Type Metadata]\n    T3 --\u003e T4[Transform Fields]\n    T4 --\u003e T5[Configure Endpoints]\n    T5 --\u003e Output[Enhanced Spec]\n\n    style Input fill:#e3f2fd\n    style T3 fill:#fff3e0\n    style Output fill:#e8f5e9\n```\n\n### 1. Vendor Extensions\n\n**BigInt Fields** (`x-algokit-bigint: true`)\n\n- Marks fields that require 64-bit integer precision\n- Applied to: `format: \"uint64\"`, `x-algorand-format: \"uint64\"`, `x-go-type: \"uint64\"`\n- Examples: `amount`, `round`, `total-apps-opted-in`\n\n**Signed Transactions** (`x-algokit-signed-txn: true`)\n\n- Identifies SignedTransaction types\n- Applied to: `x-algorand-format: \"SignedTransaction\"`\n- Enables proper msgpack serialization\n\n**Locals Reference** (`x-algokit-locals-reference: true`)\n\n- Marks schemas that reference an account's local state for an application\n- Applied to: `ApplicationLocalReference` schema\n- Enables proper handling of local state references in code generation\n\n### 2. Field Corrections\n\n**Required Fields**\n\n- Removes incorrect required fields that are actually optional\n- Example: `approval-program` and `clear-state-program` in `ApplicationParams`\n\n**Field Constraints**\n\n- Adds proper min/max values\n- Example: `num-uint` and `num-byte-slice` (0-64 range)\n\n### 3. Msgpack Endpoint Marking\n\n**Msgpack-Only Endpoints** (Algod)\n\n- Endpoints that only accept/return msgpack:\n  - `POST /v2/transactions` - Raw transaction submission\n  - `GET /v2/transactions/pending/{txid}` - Pending transaction info\n  - `GET /v2/blocks/{round}` - Block retrieval\n\n**JSON-Only Endpoints** (Algod)\n\n- Forces JSON for specific endpoints:\n  - `GET /v2/accounts/{address}` - Account information\n  - `GET /v2/accounts/{address}/assets/{asset-id}` - Asset holdings\n\n### 4. Bug Fixes\n\n- **Missing Descriptions**: Adds required description fields for responses\n- **Pydantic Recursion**: Fixes circular reference issues\n- **KMD Prefixes**: Removes redundant `APIVn` prefixes from schema names\n\n## Using in Language Repositories\n\nThis standalone converter is designed to be consumed by language-specific repositories for code generation.\n\n### As a Git Submodule\n\n```bash\n# In your language repo (e.g., algokit-core, algokit-utils-py)\ngit submodule add \u003crepo-url\u003e api-specs\n\n# Update specs\ncd api-specs\nnpm install\nnpm run convert-openapi\n\n# Reference specs in your generators\n./api-specs/specs/algod.oas3.json\n```\n\n### Direct Integration\n\nCopy the generated specs to your project:\n\n```bash\n# From this repo\nnpm run convert-openapi\n\n# Copy to your project\ncp specs/*.oas3.json /path/to/your/project/specs/\n```\n\n## Development\n\n### Running Tests\n\n```bash\nnpm test\n```\n\n### Linting\n\n```bash\nnpm run lint\n```\n\n### Formatting\n\n```bash\nnpm run format\n```\n\n## Version Tracking\n\nThe converter fetches specs from the latest stable release tags:\n\n- **Algod/KMD**: Latest stable tag from `go-algorand` (format: `v3.x.x-stable`)\n- **Indexer**: Latest tag from `indexer` repository\n\nGenerated specs include metadata about their source version in console output.\n\n## Advanced Configuration\n\nThis section covers how to edit `config.ts` to customize OpenAPI transformations for Algorand specs.\n\n### Config Structure\n\nThree main config objects in `config.ts`:\n\n- `ALGOD_CONFIG` - Algod API transformations\n- `INDEXER_CONFIG` - Indexer API transformations\n- `KMD_CONFIG` - KMD API transformations\n\nEach config is typed as `ProcessingConfig` (see `types.ts` for full interface).\n\n### ProcessingConfig Fields\n\n| Field                       | Type                         | Description                                                                  |\n| --------------------------- | ---------------------------- | ---------------------------------------------------------------------------- |\n| `sourceUrl`                 | `string`                     | GitHub raw URL for source spec                                               |\n| `outputPath`                | `string`                     | Output file path for converted spec                                          |\n| `vendorExtensionTransforms` | `VendorExtensionTransform[]` | Transform vendor extensions (e.g., `x-algorand-format` → `x-algokit-bigint`) |\n| `requiredFieldTransforms`   | `RequiredFieldTransform[]`   | Add/remove fields from schema `required` arrays                              |\n| `fieldTransforms`           | `FieldTransform[]`           | Add/remove properties on specific fields                                     |\n| `msgpackOnlyEndpoints`      | `FilterEndpoint[]`           | Mark endpoints as msgpack-only                                               |\n| `jsonOnlyEndpoints`         | `FilterEndpoint[]`           | Mark endpoints as JSON-only                                                  |\n| `customSchemas`             | `CustomSchema[]`             | Inject custom schema definitions                                             |\n| `schemaRenames`             | `SchemaRename[]`             | Rename schema objects                                                        |\n| `schemaFieldRenames`        | `SchemaFieldRename[]`        | Rename fields within schemas                                                 |\n| `removeSchemaFields`        | `string[]`                   | Remove specific fields from all schemas                                      |\n| `makeAllFieldsRequired`     | `boolean`                    | Make all schema properties required                                          |\n| `endpointTagTransforms`     | `EndpointTagTransform[]`     | Add/remove tags on endpoints                                                 |\n| `schemaVendorExtensions`    | `SchemaVendorExtension[]`    | Add vendor extensions to schemas                                             |\n\n### Common Configuration Tasks\n\n#### Add a Vendor Extension Transform\n\nTransform source properties to target vendor extensions:\n\n```typescript\nvendorExtensionTransforms: [\n  {\n    sourceProperty: \"x-algorand-format\",\n    sourceValue: \"uint64\",\n    targetProperty: \"x-algokit-bigint\",\n    targetValue: true,\n    removeSource: true, // Remove x-algorand-format after transform\n  },\n];\n```\n\n#### Add a Field Rename\n\nRename fields across all schemas or within specific schemas:\n\n```typescript\nfieldTransforms: [\n  {\n    fieldName: \"num-uint\",\n    schemaName: \"ApplicationStateSchema\", // Optional: target specific schema\n    addItems: {\n      \"x-algokit-field-rename\": \"num_uints\",\n    },\n  },\n];\n```\n\n#### Mark BigInt Fields\n\nAdd bigint markers to 64-bit integer fields:\n\n```typescript\nfieldTransforms: [\n  {\n    fieldName: \"amount\",\n    addItems: {\n      \"x-algokit-bigint\": true,\n    },\n  },\n];\n```\n\nOr use vendor extension transforms:\n\n```typescript\nvendorExtensionTransforms: [\n  {\n    sourceProperty: \"format\",\n    sourceValue: \"uint64\",\n    targetProperty: \"x-algokit-bigint\",\n    targetValue: true,\n    removeSource: false,\n  },\n];\n```\n\n#### Add Required Field Transforms\n\nRemove incorrectly marked required fields:\n\n```typescript\nrequiredFieldTransforms: [\n  {\n    schemaName: \"ApplicationParams\",\n    fieldName: \"approval-program\",\n    makeRequired: false, // Remove from required array\n  },\n  {\n    schemaName: \"Transaction\",\n    fieldName: [\"fee\", \"sender\"], // Multiple fields\n    makeRequired: true, // Add to required array\n  },\n];\n```\n\n#### Add Field Constraints\n\nAdd min/max values or other constraints:\n\n```typescript\nfieldTransforms: [\n  {\n    fieldName: \"num-uint\",\n    removeItems: [\"format\"], // Remove existing format\n    addItems: {\n      minimum: 0,\n      maximum: 64,\n    },\n  },\n];\n```\n\n#### Add Schema Vendor Extensions\n\nAdd vendor extensions at the schema level:\n\n```typescript\nschemaVendorExtensions: [\n  {\n    schemaName: \"BoxReference\",\n    extension: \"x-algokit-box-reference\",\n    value: true,\n  },\n];\n```\n\n#### Mark Msgpack/JSON Endpoints\n\nForce specific content types for endpoints:\n\n```typescript\nmsgpackOnlyEndpoints: [\n  { path: \"/v2/blocks/{round}\", methods: [\"get\"] },\n],\njsonOnlyEndpoints: [\n  { path: \"/v2/accounts/{address}\", methods: [\"get\"] },\n]\n```\n\n#### Add Endpoint Tags\n\nTag endpoints for filtering (e.g., mark deprecated):\n\n```typescript\nendpointTagTransforms: [\n  {\n    path: \"/v2/teal/dryrun\",\n    methods: [\"post\"],\n    addTags: [\"skip\", \"deprecated\"],\n  },\n];\n```\n\n#### Rename Schemas\n\nRename schema objects (useful for KMD API version prefixes):\n\n```typescript\nschemaRenames: [{ from: \"APIV1POSTKeyResponse\", to: \"GenerateKeyResponse\" }];\n```\n\n#### Rename Schema Fields\n\nRename fields within specific schemas:\n\n```typescript\nschemaFieldRenames: [\n  {\n    schemaName: \"MultisigSig\",\n    fieldRenames: [\n      { from: \"Subsigs\", to: \"subsig\" },\n      { from: \"Threshold\", to: \"thr\" },\n    ],\n  },\n];\n```\n\n### Testing Changes\n\nAfter editing `config.ts`:\n\n```bash\n# Convert the modified spec\nnpm run convert-algod  # or convert-indexer, convert-kmd\n\n# Check what changed\ngit diff specs/algod.oas3.json\n\n# Validate the output\nnpm run lint\n```\n\n### Reference\n\n- **Full type definitions**: See `types.ts` for complete interface definitions\n- **Existing configs**: Review `ALGOD_CONFIG`, `KMD_CONFIG`, `INDEXER_CONFIG` in `config.ts` for examples\n- **Shared transforms**: Use `UINT64_TRANSFORMS`, `SIGNED_TXN_TRANSFORM`, `BOX_REFERENCE_TRANSFORM` for common patterns\n\n## Troubleshooting\n\n### Rate Limiting\n\nIf you encounter GitHub API rate limits:\n\n- Wait for the rate limit to reset\n- Use authenticated requests (set `GITHUB_TOKEN` environment variable)\n- Use cached specs if available\n\n### Conversion Failures\n\nIf conversion fails:\n\n- Check network connectivity\n- Verify the source URLs are accessible\n- Ensure Node.js and npm are up to date\n- Check console output for specific error messages\n\n## CI/CD Automation\n\nThis repository includes automated workflows for maintaining and releasing OpenAPI specifications.\n\n### Weekly Sync Workflow\n\n**File**: `.github/workflows/openapi_sync.yml`\n\nRuns every Monday at 9:00 AM UTC to detect upstream changes in Algorand's API specifications.\n\n**What it does**:\n\n- Fetches latest specs from go-algorand and indexer repositories\n- Converts them using the same process as `npm run convert-openapi`\n- Compares generated files with committed versions\n- Fails if differences are detected (indicating upstream changes)\n\n**When it fails**:\n\n1. Run `npm run convert-openapi` locally\n2. Review the changes with `git diff`\n3. Commit and push the updated specs\n\n**Manual trigger**:\n\n```bash\n# Via GitHub Actions UI: Actions \u003e OpenAPI Sync \u003e Run workflow\n```\n\n### Release Workflow\n\n**File**: `.github/workflows/openapi_release.yml`\n\nCreates GitHub releases with converted OpenAPI 3.0 specifications as downloadable assets.\n\n**What it does**:\n\n- Converts all three API specs (algod, indexer, kmd)\n- Creates a GitHub release with the specs as attachments\n- Includes metadata about source versions in release notes\n\n**Trigger methods**:\n\n1. **Push a git tag**:\n\n```bash\ngit tag v1.0.0\ngit push origin v1.0.0\n```\n\n2. **Manual workflow dispatch**:\n\n```bash\n# Via GitHub Actions UI: Actions \u003e OpenAPI Release \u003e Run workflow\n# Enter tag name: v1.0.0\n```\n\n**Using released specs**:\n\n```bash\n# Download from releases\ncurl -LO https://github.com/YOUR_ORG/algokit-configs/releases/download/v1.0.0/algod.oas3.json\n\n# Use with any OpenAPI code generator\nopenapi-generator generate -i algod.oas3.json -g python -o ./client\n```\n\n## Why OpenAPI 3.0?\n\nOpenAPI 3.0 is preferred over Swagger 2.0 for several reasons:\n\n- **Enhanced Schema Features**: Better support for complex types and validation\n- **Component Reusability**: Improved `$ref` resolution and schema composition\n- **Better Type Definitions**: More precise type specifications\n- **Wider Tool Support**: Better compatibility with modern code generators\n- **Vendor Extensions**: Better support for custom metadata\n\n## Contributing\n\nContributions are welcome! Please ensure:\n\n1. New transformations are well-documented\n2. Changes maintain backward compatibility with existing generators\n3. Test your changes with all three API specs\n4. Update this README with any new features or configuration options\n\n## License\n\nMIT\n\n## Related Projects\n\n- [algokit-core](https://github.com/algorandfoundation/algokit-core) - Rust and TypeScript implementations\n- [algokit-utils-py](https://github.com/algorandfoundation/algokit-utils-py) - Python implementation\n- [go-algorand](https://github.com/algorand/go-algorand) - Source of Algod and KMD specs\n- [indexer](https://github.com/algorand/indexer) - Source of Indexer spec\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Falgorandfoundation%2Falgokit-oas-generator","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Falgorandfoundation%2Falgokit-oas-generator","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Falgorandfoundation%2Falgokit-oas-generator/lists"}