{"id":31626347,"url":"https://github.com/fs1n/powershell-openapi-wrapper","last_synced_at":"2025-10-15T03:29:40.381Z","repository":{"id":318037264,"uuid":"1067416619","full_name":"fs1n/Powershell-OpenAPI-Wrapper","owner":"fs1n","description":"Powershell Script to Build API Wrapper Powershell module with Markdown documentation!","archived":false,"fork":false,"pushed_at":"2025-10-04T16:39:48.000Z","size":65,"stargazers_count":3,"open_issues_count":1,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-10-04T18:16:57.676Z","etag":null,"topics":["api-wrapper","powershell","powershell-generator","powershell-module","powershell-modules","swagger-codegen"],"latest_commit_sha":null,"homepage":"","language":"PowerShell","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/fs1n.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","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-09-30T20:37:12.000Z","updated_at":"2025-10-04T17:44:00.000Z","dependencies_parsed_at":"2025-10-04T18:17:05.439Z","dependency_job_id":"48577f53-ebb2-4169-af4c-bb4d714fa2ce","html_url":"https://github.com/fs1n/Powershell-OpenAPI-Wrapper","commit_stats":null,"previous_names":["fs1n/powershell-openapi-wrapper"],"tags_count":1,"template":false,"template_full_name":null,"purl":"pkg:github/fs1n/Powershell-OpenAPI-Wrapper","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fs1n%2FPowershell-OpenAPI-Wrapper","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fs1n%2FPowershell-OpenAPI-Wrapper/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fs1n%2FPowershell-OpenAPI-Wrapper/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fs1n%2FPowershell-OpenAPI-Wrapper/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/fs1n","download_url":"https://codeload.github.com/fs1n/Powershell-OpenAPI-Wrapper/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fs1n%2FPowershell-OpenAPI-Wrapper/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":279042943,"owners_count":26091351,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-10-15T02:00:07.814Z","response_time":56,"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":["api-wrapper","powershell","powershell-generator","powershell-module","powershell-modules","swagger-codegen"],"created_at":"2025-10-06T19:50:58.957Z","updated_at":"2025-10-15T03:29:40.349Z","avatar_url":"https://github.com/fs1n.png","language":"PowerShell","funding_links":[],"categories":[],"sub_categories":[],"readme":"# PowerShell OpenAPI Wrapper Generator\n\n\u003e **Automatically generate PowerShell modules from OpenAPI/Swagger specifications with universal enhancement levels**\n\nTransform any OpenAPI specification into a fully-featured Powershell API Wrapper module!\n\n| Implemented Features:\n\n| Feature | Status | Description |\n|---------|--------|-------------|\n| **Universal Generator** | ✅ Complete | Single generator with configurable enhancement levels |\n| **Parameter Extraction** | ✅ Complete | Full OpenAPI parameter extraction for Advanced/Expert levels |\n| **YAML Auto-Install** | ✅ Complete | Automatic PowerShell-Yaml module installation |\n| **Modular Structure** | ✅ Complete | Automatic modular structure for large APIs (\u003e50 functions) |\n| **Interactive Wizard** | ✅ Complete | Guided setup with enhancement level selection |\n| **Enhancement Levels** | ✅ Complete | Basic → Standard → Advanced → Expert progression |\n| **Query Parameter Handling** | ✅ Complete | Automatic URL encoding and parameter building |\n| **Enterprise Error Handling** | ✅ Complete | Retry logic and advanced error handling in Expert level |tus | \n| **Universal Generator** | ✅ Complete | Single generator with configurable enhancement levels |\n| **Parameter Extraction** | ✅ Complete | Full OpenAPI parameter extraction for Advanced/Expert levels |\n| **YAML Auto-Install** | ✅ Complete | Automatic PowerShell-Yaml module installation |\n| **Modular Structure** | ✅ Complete | Automatic modular structure for large APIs (\u003e50 functions) |\n| **Interactive Wizard** | ✅ Complete | Guided setup with enhancement level selection |\n| **Enhancement Levels** | ✅ Complete | Basic → Standard → Advanced → Expert progression |\n| **Query Parameter Handling** | ✅ Complete | Automatic URL encoding and parameter building |\n| **Enterprise Error Handling** | ✅ Complete | Retry logic and advanced error handling in Expert level |\n\n## 📊 Tested APIs\n\nSuccessfully tested with real-world APIs:\n\n| API | Functions | Parameters | Enhancement Level | Structure |\n|-----|-----------|------------|-------------------|-----------|\n| **Hitobito MiData** | 19 functions | **170+ parameters** | Advanced/Expert | Single file |\n| **Swagger Petstore** | 20 functions | Basic parameters | All levels | Single file |\n| **SEPPmail Hera** | 309 functions | Complex | All levels | Modular structure |\n| **Custom Enterprise APIs** | Various | Various | All levels | Auto-detected |\n\n### Parameter Extraction Success\n\nThe **MiData API** demonstrates the power of Advanced/Expert level parameter extraction:\n\n- ✅ **Basic parameters**: `include`, `sort`, `fields[people]`\n- ✅ **Filter parameters**: 50+ filter combinations (`eq`, `not_eq`, `prefix`, `suffix`, `match`, etc.)\n- ✅ **Field selectors**: `fields[groups]`, `fields[roles]`, `fields[phone_numbers]`, etc.\n- ✅ **Type conversion**: Automatic string, array, boolean, integer parameter types\n- ✅ **Safe naming**: Complex API parameters converted to PowerShell-safe namese with idiomatic function names, comprehensive parameter extraction, and built-in help documentation. Now with universal architecture supporting Basic to Expert enhancement levels!\n\n## 🚀 Quick Start\n\n### Option 1: Interactive Wizard (Recommended)\n```powershell\n# Start the interactive setup wizard\n.\\PowerShell-OpenAPI-Generator.ps1 -Interactive\n\n# Follow the guided setup:\n# 1. Select OpenAPI file (or choose from examples)\n# 2. Enter module name\n# 3. Choose output directory\n# 4. Select enhancement level (Basic/Standard/Advanced/Expert)\n# 5. Generate!\n```\n\n### Option 2: Command Line Generation\n```powershell\n# Basic Level - Simple HTTP requests\n.\\PowerShell-OpenAPI-Generator.ps1 -OpenAPIPath \".\\examples\\midata.yaml\" -ModuleName \"MiDataAPI\" -OutputPath \".\\MiDataAPI\" -EnhancementLevel \"Basic\"\n\n# Advanced Level - Full parameter extraction\n.\\PowerShell-OpenAPI-Generator.ps1 -OpenAPIPath \".\\examples\\midata.yaml\" -ModuleName \"MiDataAPI\" -OutputPath \".\\MiDataAPI\" -EnhancementLevel \"Advanced\" -GenerateReadme\n\n# Expert Level - Enterprise features with retry logic\n.\\PowerShell-OpenAPI-Generator.ps1 -OpenAPIPath \".\\examples\\midata.yaml\" -ModuleName \"MiDataAPI\" -OutputPath \".\\MiDataAPI\" -EnhancementLevel \"Expert\" -GenerateReadme\n```\n\n### Option 3: Quick Mode (Legacy)\n```powershell\n# Generate with Quick Mode (equivalent to Basic level)\n.\\PowerShell-OpenAPI-Generator.ps1 -OpenAPIPath \".\\examples\\midata.yaml\" -ModuleName \"MiDataAPI\" -OutputPath \".\\MiDataAPI\" -QuickMode\n```\n\n## ✨ Key Features\n\n| Feature | Description |\n|---------|-------------|\n| 🎯 **PowerShell-Idiomatic** | `Get-Pet`, `New-Pet`, `Set-Pet` instead of generic `Invoke-*` |\n| 📚 **Rich Documentation** | Complete comment-based help from OpenAPI descriptions |\n| 🔒 **Parameter Extraction** | **Full OpenAPI parameter extraction** with 170+ parameters for complex APIs |\n| 🌐 **Universal Format** | Supports both YAML and JSON OpenAPI specifications |\n| 🛡️ **Safe Parameter Names** | Converts complex API parameters to PowerShell-safe names |\n| 🧙‍♂️ **Interactive Wizard** | Guided setup process with enhancement level selection |\n| ⚡ **Universal Architecture** | Single codebase with configurable enhancement levels |\n| 🗂️ **Modular Structure** | Automatically creates modular structure for large APIs (\u003e50 functions) |\n| 🎛️ **Enhancement Levels** | Basic → Standard → Advanced → Expert progression |\n| 🔄 **Auto-Installation** | Automatic PowerShell-Yaml module installation for YAML support |\n\n## 🎛️ Enhancement Levels\n\n| Level | Features | Use Case |\n|-------|----------|----------|\n| **Basic** | Simple HTTP requests, BaseUri, Headers | Quick prototyping, simple APIs |\n| **Standard** | + Timeout management, enhanced headers | Production use, reliability |\n| **Advanced** | + **Full parameter extraction**, Body handling | **Complex APIs with many parameters** |\n| **Expert** | + Retry logic, enterprise error handling | Mission-critical applications |\n\n### Real Parameter Extraction Example\n\n**Advanced/Expert Level** extracts all OpenAPI parameters:\n\n```powershell\n# Generated function with 170+ parameters from Hitobito MiData API\nGet-listPeople -BaseUri \"https://\u003cHitobito\u003e/api\" `\n               -filter_first_name__eq_ \"Max\" `\n               -filter_last_name__prefix_ \"Muster\" `\n               -filter_email__suffix_ \"@pfadi.ch\" `\n               -sort \"first_name\" `\n               -fields_people_ @(\"first_name\", \"last_name\", \"email\") `\n               -include \"groups,roles\"\n```\n\n## 🏗️ Project Structure\n\n```\nPowerShell-OpenAPI-Wrapper/\n├── 🚀 PowerShell-OpenAPI-Generator.ps1  # Universal generator with enhancement levels\n├── 📄 README.md                         # This documentation\n├── 📂 src/                              # Legacy source code modules (deprecated)\n│   ├── 📂 Core/                         # Core functionality (not used in universal generator)\n│   └── 📂 Enhancements/                 # Enhancement modules (replaced by universal system)\n├── 📂 examples/                         # Example OpenAPI specifications\n│   ├── swagger.json                     # Petstore API example  \n│   └── swagger.yaml                     # YAML format example\n└── 📂 docs/                            # Documentation and guides\n```\n\n## 📁 Generated Module Structure\n\n### Small APIs (≤50 functions):\n```\nMyModule/\n├── MyModule.psd1          # PowerShell module manifest\n├── MyModule.psm1          # All functions in one file\n└── README.md              # Generated documentation (if requested)\n```\n\n### Large APIs (\u003e50 functions):\n```\nMyModule/\n├── MyModule.psd1          # PowerShell module manifest\n├── MyModule.psm1          # Main module file (imports functions)\n├── README.md              # Generated documentation\n└── Functions/             # Individual function files\n    ├── Get-listPeople.ps1\n    ├── Get-Event.ps1\n    └── ... (300+ more functions)\n```\n\n## 🛠️ Generated Function Examples\n\nThe universal generator creates PowerShell functions following standard verb conventions with different enhancement levels:\n\n| OpenAPI Endpoint | Generated PowerShell Function | Enhancement Level |\n|------------------|------------------------------|-------------------|\n| `GET /api/people` | `Get-listPeople` | All levels |\n| `GET /api/people/{id}` | `Get-Person` | All levels |\n| `POST /api/roles` | `New-createRole` | All levels |\n| `PUT /api/people/{id}` | `Set-updatePerson` | All levels |\n| `DELETE /api/roles/{id}` | `Remove-Role` | All levels |\n\n### Enhancement Level Comparison\n\n#### Basic Level\n```powershell\nfunction Get-listPeople {\n    param(\n        [Parameter(Mandatory = $true)]\n        [string]$BaseUri,\n        [hashtable]$Headers = @{}\n    )\n    # Simple HTTP request implementation\n}\n```\n\n#### Advanced Level (Full Parameter Extraction)\n```powershell\nfunction Get-listPeople {\n    param(\n        [Parameter(Mandatory = $true)]\n        [string]$BaseUri,\n        [hashtable]$Headers = @{},\n        [int]$TimeoutSec = 30,\n        [hashtable]$Body = @{},\n        # 170+ extracted OpenAPI parameters:\n        [string]$include,\n        [string]$sort,\n        [string[]]$filter_first_name__eq_,\n        [string[]]$filter_last_name__prefix_,\n        [string[]]$filter_email__match_,\n        # ... and 165+ more parameters\n    )\n    # Advanced implementation with query parameter handling\n}\n```\n\n#### Expert Level\n```powershell\nfunction Get-listPeople {\n    param(\n        # All Advanced parameters plus:\n        [switch]$PassThru,\n        [ValidateSet('Default', 'Ignore', 'Retry')]\n        [string]$ErrorHandling = 'Default'\n    )\n    # Expert implementation with retry logic and Professional error handling\n}\n```\n\n### Real-World Usage Example\n\n```powershell\n# Import your generated module\nImport-Module \".\\MiDataAPI\\MiDataAPI.psd1\"\n\n# List available functions\nGet-Command -Module MiDataAPI\n\n# Get help for any function (shows all 170+ parameters for Advanced/Expert level)\nGet-Help Get-listPeople -Full\n\n# Basic Level usage\nGet-listPeople -BaseUri \"https://api.midata.cevi.ch\"\n\n# Advanced Level usage with extracted parameters\nGet-listPeople -BaseUri \"https://\u003cHitobito\u003e/api\" `\n               -filter_first_name__eq_ \"Max\" `\n               -filter_last_name__prefix_ \"Muster\" `\n               -filter_email__suffix_ \"@pfadi.ch\" `\n               -sort \"first_name\" `\n               -fields_people_ @(\"first_name\", \"last_name\", \"email\") `\n               -include \"groups,roles\"\n\n# Expert Level usage with retry logic\nGet-listPeople -BaseUri \"https://\u003cHitobito\u003e/api\" `\n               -filter_first_name__eq_ \"Max\" `\n               -ErrorHandling \"Retry\" `\n               -TimeoutSec 60\n\n# For large APIs, use selective imports for better performance\nImport-Module \".\\LargeModule\\LargeAPI.psd1\" -Function 'Get-*'\n```\n\n## 📋 Requirements\n\n- **PowerShell 5.1+** (Windows PowerShell or PowerShell Core)\n- **YAML Support** (automatically installed):\n  - The generator automatically installs `PowerShell-Yaml` module if needed\n  - PowerShell 7.0+ has enhanced YAML support\n\n### Automatic YAML Installation\n\nThe universal generator automatically handles YAML dependencies:\n\n```powershell\n# The generator will automatically:\n# 1. Detect YAML files (.yaml/.yml)\n# 2. Check for ConvertFrom-Yaml availability\n# 3. Install PowerShell-Yaml module if needed\n# 4. Import and use the module\n\n# No manual installation required!\n```\n\n## 📊 Tested APIs\n\nSuccessfully tested with:\n\n| API | Functions | Complexity | Structure |\n|-----|-----------|------------|-----------|\n| **Swagger Petstore** | 20 functions | Simple | Single file |\n| **SEPPmail Cloud API (Hera)** | 309 functions | Complex | Modular structure |\n| **Custom APIs** | Various | Various | Auto-detected |\n\n## 🚀 Advanced Usage\n\n### Enhancement Level Selection\n\n```powershell\n# Basic: Quick prototyping\n.\\PowerShell-OpenAPI-Generator.ps1 -OpenAPIPath \"api.yaml\" -ModuleName \"API\" -EnhancementLevel \"Basic\"\n\n# Standard: Production reliability  \n.\\PowerShell-OpenAPI-Generator.ps1 -OpenAPIPath \"api.yaml\" -ModuleName \"API\" -EnhancementLevel \"Standard\"\n\n# Advanced: Full parameter extraction (recommended for complex APIs)\n.\\PowerShell-OpenAPI-Generator.ps1 -OpenAPIPath \"api.yaml\" -ModuleName \"API\" -EnhancementLevel \"Advanced\"\n\n# Expert: Enterprise features with retry logic\n.\\PowerShell-OpenAPI-Generator.ps1 -OpenAPIPath \"api.yaml\" -ModuleName \"API\" -EnhancementLevel \"Expert\"\n```\n\n### Large API Performance Tips\n\n```powershell\n# For APIs with 100+ functions, use selective imports\nImport-Module \".\\MyLargeAPI\\API.psd1\" -Function 'Get-*'\n\n# Check function count and structure\nGet-Command -Module MyAPI | Measure-Object\nTest-Path \".\\MyAPI\\Functions\\\"  # True if modular structure used\n\n# Get statistics about your generated module\nGet-Command -Module MyAPI | Group-Object { ($_.Name -split '-')[0] }\n```\n\n### Batch Generation\n\n```powershell\n# Generate multiple modules from different specs\n$specs = Get-ChildItem \".\\specs\\\" -Filter \"*.yaml\"\nforeach ($spec in $specs) {\n    $moduleName = $spec.BaseName + \"API\"\n    .\\PowerShell-OpenAPI-Generator.ps1 -OpenAPIPath $spec.FullName -ModuleName $moduleName -OutputPath \".\\modules\\$moduleName\" -EnhancementLevel \"Advanced\"\n}\n```\n\n## 🛠️ Development \u0026 Customization\n\n### Universal Architecture\n\nThe current architecture uses a single universal generator (`PowerShell-OpenAPI-Generator.ps1`) with:\n\n- **Universal Helper Functions**: `ConvertTo-SafeProperty`, `Get-SafeObjectKeys`\n- **Parameter Extraction Engine**: `Get-OpenAPIParameters` for Advanced/Expert levels\n- **Universal Function Generator**: `New-UniversalFunction` with configurable enhancement levels\n- **Universal Module Generator**: `New-UniversalModule` with smart structure detection\n\n### Legacy Components (Deprecated)\n\n- `src\\Core\\*` - Legacy core modules (replaced by universal architecture)\n- `src\\Enhancements\\*` - Legacy enhancement system (replaced by enhancement levels)\n\n### Extending Enhancement Levels\n\n```powershell\n# The enhancement levels are defined in New-UniversalFunction\n# To add new levels, modify the switch statement:\n\nswitch ($Level) {\n    'Basic' { # Simple implementation }\n    'Standard' { # + Timeout management }\n    'Advanced' { # + Parameter extraction }\n    'Expert' { # + Retry logic }\n    'Enterprise' { # Your new level here }\n}\n```\n\n## 🛠️ Troubleshooting\n\n### Common Issues\n\n**YAML parsing (no longer needed - auto-installed):**\n```powershell\n# The generator now automatically installs PowerShell-Yaml\n# No manual intervention required!\n```\n\n**Large API performance:**\n```powershell\n# Use modular imports for large APIs\nImport-Module \".\\MyAPI\\API.psd1\" -Function 'Get-Users*'\n\n# Check if modular structure was used (\u003e50 functions)\nTest-Path \".\\MyAPI\\Functions\\\"\n```\n\n**Parameter conflicts:**\n```powershell\n# Advanced/Expert level converts complex parameter names safely\n# Original: filter[first_name][eq] \n# PowerShell: filter_first_name__eq_\n\n# Use Get-Help to see parameter documentation\nGet-Help Get-listPeople -Parameter filter_first_name__eq_\n```\n\n**Enhancement level selection:**\n```powershell\n# If unsure which level to use:\n# Basic: Testing/prototyping\n# Standard: Production use\n# Advanced: APIs with many parameters (recommended)  \n# Expert: Mission-critical with retry needs\n```\n\n## 🎯 Roadmap\n\n- ✅ **Universal Architecture** - Completed\n- ✅ **Interactive Wizard** - Completed\n- ✅ **Enhancement Levels** - Completed (Basic/Standard/Advanced/Expert)\n- ✅ **Parameter Extraction** - Completed (170+ parameters from complex APIs)\n- ✅ **Large API Support** - Completed  \n- ✅ **Modular Architecture** - Completed\n- ✅ **YAML Auto-Install** - Completed\n- 🚧 **Path Parameter Support** - In Progress (currently static paths)\n- � **Authentication Schemes** - Planned (OAuth2, JWT, API Key detection)\n- 📋 **Request Body Schemas** - Planned (complex object validation)\n- 📋 **Response Validation** - Planned (schema-based response validation)\n- 📋 **Testing Framework** - Planned (automated Pester tests)\n\n### Recent Achievements (v3.0.0)\n\n- **Universal Generator**: Single codebase replacing separate Quick/Enhanced modes\n- **Full Parameter Extraction**: Advanced/Expert levels extract all OpenAPI parameters\n- **Safe Parameter Names**: Complex API parameters converted to PowerShell-safe names\n- **Enhancement Progression**: Clear upgrade path from Basic to Expert functionality\n- **Enterprise Features**: Retry logic, error handling, timeout management\n\n## 🤝 Contributing\n\nWe welcome contributions! Areas of interest:\n\n- **Path Parameter Support**: Dynamic path parameter replacement (`/api/people/{id}`)\n- **Authentication Schemes**: OAuth2, JWT, API Key detection and implementation\n- **Request Body Schemas**: Complex object validation for POST/PUT operations  \n- **Response Validation**: Schema-based response validation and type conversion\n- **Testing Framework**: Automated Pester tests for generated functions\n- **Performance Optimization**: Further improvements for very large APIs (1000+ functions)\n\n### Development Setup\n\n```powershell\n# Clone and test the universal generator\ngit clone \u003crepository\u003e\ncd PowerShell-OpenAPI-Wrapper\n\n# Test with provided examples\n.\\PowerShell-OpenAPI-Generator.ps1 -OpenAPIPath \"examples\\midata.yaml\" -ModuleName \"TestAPI\" -EnhancementLevel \"Advanced\" -OutputPath \"TestAPI\"\n\n# Verify parameter extraction\nImport-Module \".\\TestAPI\\TestAPI.psd1\"\nGet-Help Get-listPeople -Parameter filter_first_name__eq_\n```\n\n## 📜 License\n\nMIT License - see [LICENSE](LICENSE) file for details.\n\n---\n\n⭐ **Star this repository if you find it useful!** ⭐\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ffs1n%2Fpowershell-openapi-wrapper","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ffs1n%2Fpowershell-openapi-wrapper","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ffs1n%2Fpowershell-openapi-wrapper/lists"}