{"id":46109560,"url":"https://github.com/AlexMA2/swaggular","last_synced_at":"2026-03-13T17:00:45.460Z","repository":{"id":338144402,"uuid":"1156714396","full_name":"AlexMA2/swaggular","owner":"AlexMA2","description":"A powerful tool to generate Angular services and models from Swagger/OpenAPI specifications.","archived":false,"fork":false,"pushed_at":"2026-02-13T03:18:03.000Z","size":319,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2026-02-13T10:56:05.057Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"TypeScript","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/AlexMA2.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","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":"2026-02-13T00:56:48.000Z","updated_at":"2026-02-13T03:20:49.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/AlexMA2/swaggular","commit_stats":null,"previous_names":["alexma2/swaggular"],"tags_count":null,"template":false,"template_full_name":null,"purl":"pkg:github/AlexMA2/swaggular","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/AlexMA2%2Fswaggular","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/AlexMA2%2Fswaggular/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/AlexMA2%2Fswaggular/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/AlexMA2%2Fswaggular/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/AlexMA2","download_url":"https://codeload.github.com/AlexMA2/swaggular/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/AlexMA2%2Fswaggular/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":30471114,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-03-13T11:00:43.441Z","status":"ssl_error","status_checked_at":"2026-03-13T11:00:23.173Z","response_time":60,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.6:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"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":[],"created_at":"2026-03-01T22:00:55.619Z","updated_at":"2026-03-13T17:00:45.453Z","avatar_url":"https://github.com/AlexMA2.png","language":"TypeScript","readme":"# Swaggular\n\nA powerful tool to generate Angular services and models from Swagger/OpenAPI specifications.\n\nYou can create a configuration file to customize the generation process.\n\nIf you want a more customized version, you are invited to download the project in github and modify the project.\n\n## Features\n\n- 🚀 Automatically generates Angular services.\n- 📦 Generates complex model interfaces.\n- 📝 Includes JSDoc comments for better developer experience.\n- 🛠️ Highly configurable.\n\n## Getting Started\n\n### Prerequisites\n\n- Node.js (v18 or higher)\n- npm or yarn\n\n### Installation\n\nTo install the tool globally:\n\n```bash\nnpm install -g swaggular\n```\n\nOr run it directly using `npx`:\n\n```bash\nnpx swaggular --input=swagger.json\n```\n\n### Usage\n\nRun the generator by providing the path to your Swagger/OpenAPI file:\n\n```bash\nswaggular --input=path/to/your/swagger.json\n```\n\n## Configuration\n\nYou can configure Swaggular using CLI arguments or a configuration file (e.g., `swaggular.config.json`).\n\n### CLI Arguments (`ArgsVariables`)\n\n| Argument | Description | Default |\n| :--- | :--- | :--- |\n| `--input`, `-i` | Path to the Swagger/OpenAPI file or URL. | `swagger.json` |\n| `--output`, `-o` | Output directory for generated files. | `results` |\n| `--mode` | Grouping mode for services: `tags` or `path`. | `path` |\n| `--ignore-segments` | Comma-separated list of URL segments to ignore when generating service names. | `api` |\n| `--no-generate` | Parse the Swagger file but do not generate any output files. useful for testing. | `false` |\n| `--config` | Path to a configuration file. | `swaggular.config.json` (if exists) |\n\n### Configuration File (`SwaggularConfig`)\n\nYou can create a `swaggular.config.json` file in your project root to define advanced configurations. Below is the detailed structure of the configuration object.\n\n#### **Properties**\n\n- **`input`** _(optional)_: `string` - Path to the input Swagger/OpenAPI file (e.g., `swagger.json`). If not specified, defaults to the basic input.\n- **`output`** _(optional)_: `string` - Path to the output directory where generated files will be saved. Default: `results`.\n- **`groupingMode`** _(optional)_: `'tags' | 'path'` - Strategy for grouping services.\n  - `'tags'`: Groups operations based on their Swagger tags.\n  - `'path'`: Groups operations based on their URL path segments.\n- **`segmentsToIgnore`** _(optional)_: `string[]` - List of URL segments to ignore when generating service names (e.g., `['api', 'v1']`).\n- **`types`** _(optional)_: `object` - Configuration for type generation and inheritance.\n  - **`extendsFrom`** _(optional)_: `InterfaceData[]` - Defines base classes that generated DTOs should extend if they match the properties.\n  - **`generic`** _(optional)_: `InterfaceData[]` - Defines generic types to replace duplicate generated classes (e.g., `PagedResultDto\u003cT\u003e`).\n- **`templates`** _(optional)_: `object` - Configuration for templates used in generation.\n  - **`service`** _(optional)_: `object` - Service template configuration.\n    - **`path`**: `string` - Path to the internal or custom service template file (e.g., `'templates/angular-service.template'`).\n    - **`httpParamsHandler`** _(optional)_: `string` - Custom logic to handle HTTP parameters (e.g., `'const params = HttpHelper.toHttpParams(${params} || {});'`). The `${params}` is a placeholder for the query parameters, it MUST exist in the string.\n    - **`httpParamsHandlerImport`** _(optional)_: `string` - Import statement for the custom parameters handler (e.g., `'import { HttpHelper } from \"@shared/utils\";'`).\n\n---\n\n#### **Object Structures**\n\n**`InterfaceData`**\n\nUsed in `types.extendsFrom` and `types.generic`.\n\n- **`name`**: `string` - The name of the interface or class.\n- **`imports`**: `string[]` - List of imports required for this interface. It has to be the name of other generated interfaces, e.g. `['SomeProperty']`.\n- **`type`**: `'interface' | 'enum' | 'type'` - The kind of TypeScript structure.\n- **`properties`**: `InterfaceDataProperty[]` - Array of properties belonging to this interface.\n- **`extendsFrom`** _(optional)_: `string[]` - Names of other interfaces this one extends. It has to be the name of other generated interfaces, e.g. `['SomeProperty']`.\n\n**`InterfaceDataProperty`**\n\nUsed in `InterfaceData.properties`.\n\n- **`name`**: `string` - The name of the property.\n- **`type`**: `string` - The TypeScript type of the property (e.g., `'string'`, `'number'`, `'T[]'`).\n- **`optional`**: `boolean` - Whether the property is optional (`?`).\n- **`comments`**: `string` - JSDoc comments or other annotations for the property. It must be surrounded by the `/** ... */` .\n\n---\n\n#### Example `swaggular.config.json`\n\n```json\n{\n  \"input\": \"swagger.json\",\n  \"output\": \"src/app/api\",\n  \"groupingMode\": \"tags\",\n  \"segmentsToIgnore\": [\"api\", \"v1\"],\n  \"types\": {\n    \"extendsFrom\": [\n      {\n        \"name\": \"PagedRequestDto\",\n        \"type\": \"interface\",\n        \"properties\": [\n          { \"name\": \"skipCount\", \"type\": \"number\", \"optional\": true, \"comments\": \"\" },\n          { \"name\": \"maxResultCount\", \"type\": \"number\", \"optional\": true, \"comments\": \"\" }\n        ],\n        \"imports\": []\n      }\n    ],\n    \"generic\": [\n      {\n        \"name\": \"PagedResultDto\",\n        \"type\": \"interface\",\n        \"properties\": [\n          { \"name\": \"items\", \"type\": \"T[]\", \"optional\": true, \"comments\": \"\" },\n          { \"name\": \"totalCount\", \"type\": \"number\", \"optional\": true, \"comments\": \"\" }\n        ],\n        \"imports\": []\n      }\n    ]\n  },\n  \"templates\": {\n    \"service\": {\n      \"path\": \"templates/angular-service.template\",\n      \"httpParamsHandlerImport\": \"import { HttpHelper } from '@shared/utils/http-helper';\",\n      \"httpParamsHandler\": \"const params = HttpHelper.toHttpParams(${params} || {});\"\n    }\n  }\n}\n```\n\nThis configuration allows you to:\n\n1. **extendsFrom**: Automatically make generated DTOs extend a base class (e.g., `PagedRequestDto`) if they share the same properties.\n2. **generic**: Automatically detect and use generic types (e.g., `PagedResultDto\u003cT\u003e`) instead of generating duplicate classes like `PagedResultDtoOfUser`.\n3. **templates.service**: Customize how HTTP parameters are handled in generated services, allowing you to use your own helper functions.\n\n## Development\n\n### Scripts\n\n- `npm run build`: Compile TypeScript to JavaScript.\n- `npm run start`: Run the compiled project.\n- `npm run serve`: Compile and run the project immediately.\n- `npm run lint`: Run ESLint to check code style.\n- `npm run format`: Format code using Prettier.\n- `npm test`: Run tests using Jest.\n\n## Contributing\n\nPlease read [CONTRIBUTING.md](CONTRIBUTING.md) for details on our code of conduct, and the process for submitting pull requests to us.\n\n### 🚀 Roadmap\n\n- [ ] Add TSDoc comments\n- [ ] Add function to identify common properties and generate interfaces without any configuration\n- [ ] Add function to generate interfaces and services for just one specific path\n\n## License\n\nThis project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.\n","funding_links":[],"categories":["Development Utilities"],"sub_categories":["Generators and Scaffolding"],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FAlexMA2%2Fswaggular","html_url":"https://awesome.ecosyste.ms/projects/github.com%2FAlexMA2%2Fswaggular","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FAlexMA2%2Fswaggular/lists"}