{"id":26558082,"url":"https://github.com/enricodeleo/aquasdk","last_synced_at":"2025-06-11T17:32:26.515Z","repository":{"id":281843361,"uuid":"946621857","full_name":"enricodeleo/aquasdk","owner":"enricodeleo","description":"Turn OpenAPI into a smooth, chainable SDK – with AquaSDK #OASv3 #openapi3 ","archived":false,"fork":false,"pushed_at":"2025-03-31T12:37:36.000Z","size":473,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-05-10T01:37:09.614Z","etag":null,"topics":["codegenerator","openapi","openapi3","sdk-js","swagger"],"latest_commit_sha":null,"homepage":"","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/enricodeleo.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE.md","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}},"created_at":"2025-03-11T12:29:35.000Z","updated_at":"2025-03-31T12:37:39.000Z","dependencies_parsed_at":"2025-03-11T13:11:16.632Z","dependency_job_id":"9a08760b-d925-4268-804f-e13a57ba454e","html_url":"https://github.com/enricodeleo/aquasdk","commit_stats":null,"previous_names":["enricodeleo/aquasdk"],"tags_count":8,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/enricodeleo%2Faquasdk","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/enricodeleo%2Faquasdk/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/enricodeleo%2Faquasdk/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/enricodeleo%2Faquasdk/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/enricodeleo","download_url":"https://codeload.github.com/enricodeleo/aquasdk/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/enricodeleo%2Faquasdk/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":259226156,"owners_count":22824865,"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","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":["codegenerator","openapi","openapi3","sdk-js","swagger"],"created_at":"2025-03-22T12:22:10.044Z","updated_at":"2025-06-11T17:32:26.510Z","avatar_url":"https://github.com/enricodeleo.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# **AquaSDK**\n\n**A modern JavaScript SDK generator from OpenAPI specs**\n\n\u003cimg src=\"logo.jpg\" alt=\"aquasdk logo\" width=\"200\"/\u003e\n\nAquaSDK is an open-source tool that generates a fully-featured JavaScript SDK from an OpenAPI specification. It enables easy integration with APIs through a chainable, **Waterline-like** syntax. AquaSDK helps you rapidly create SDKs, making it easier to interact with RESTful APIs.\n\n### **Why**\n\n**Waterline ORM**, commonly used in [Sails.js](https://sailsjs.com/), is often praised for its intuitive and flexible syntax, which simplifies database interactions.\n\n---\n\n## 📦 **Installation**\n\nYou can easily install AquaSDK globally, or locally for development.\n\n### Global Installation\nInstall AquaSDK globally for command-line access:\n```bash\nnpm install -g aquasdk\n```\n\n### Local Installation (for development)\nTo install locally and contribute to the project:\n```bash\n# Clone the repository\ngit clone https://github.com/enricodeleo/aquasdk.git\ncd aquasdk\nnpm install\nnpm link\n```\n\n---\n\n## 🛠 **Usage**\n\nOnce installed, you can use the `generate-sdk` command to generate a JavaScript SDK from an OpenAPI specification.\n\n```bash\ngenerate-sdk \u003cswagger-file-path\u003e \u003coutput-directory\u003e \u003cversion\u003e [--verbose]\n```\n\n### Arguments\n\n- `swagger-file-path`: Path to your OpenAPI/Swagger JSON file (default: `./swagger.json`)\n- `output-directory`: Directory where the SDK will be generated (default: `./sdk`)\n- `version`: The version number of the generated SDK (default: `1.0.0`)\n- `--verbose`: Flag for detailed logging\n\n### Example\n\n```bash\ngenerate-sdk ./swagger.json ./sdk 1.0.0 --verbose\n```\n\n---\n\n## 🎉 **Features of the Generated SDK**\n\nThe generated SDK includes the following features:\n\n- **Waterline-like Syntax**: Chainable query methods for interacting with your API, similar to Sails.js/Waterline. Brings ORM-style chaining (`.find()`, `.limit()`, `.sort()`) to REST API calls, making client-side code more expressive.\n- **OpenAPI-Driven Development**: Automates SDK generation from specs, reducing human error and ensuring alignment with API contracts.\n- **Promise-based API**: All API calls return promises, making them compatible with `async/await`.\n- **Response Headers Access**: All API responses include both data and headers, allowing access to important HTTP header information.\n- **Comprehensive Error Handling**: Includes detailed and meaningful error messages.\n- **Support for Associations**: Handling relationships via `.populate()` (if implemented) would mirror Waterline's eager-loading, a standout feature for nested resources.\n- **Configurable HTTP Client**: Support for additional Axios configuration options to customize timeout, headers, and other HTTP client settings.\n\n---\n\n## 💻 **SDK API Example**\n\nOnce the SDK is generated, you can use it as follows:\n\n### Example Code\n```javascript\nimport API from './sdk/index.js';\n\n// Initialize the SDK\nconst api = new API({\n  baseUrl: 'https://api.example.com',\n  auth: {\n    token: 'your-auth-token'\n    // Or use basic auth\n    // username: 'user',\n    // password: 'pass'\n  },\n  // Additional Axios configuration options\n  timeout: 5000,\n  headers: {\n    'Custom-Header': 'value'\n  },\n  // Custom parameter serializer (recommended for complex queries and nested objects)\n  paramsSerializer: {\n    serialize: (params) =\u003e {\n      // Using a library like 'qs' for proper handling of nested objects and arrays\n      // import { stringify } from 'qs';\n      return stringify(params, {\n        arrayFormat: 'brackets',\n        encode: false,\n        allowDots: true\n      });\n    }\n  }\n  \n  // Alternative format for Axios v1.x\n  /*\n  paramsSerializer: {\n    encode: (value) =\u003e value, // Optional custom encoder\n    serialize: (params) =\u003e stringify(params, { \n      arrayFormat: 'brackets',\n      encode: false,\n      allowDots: true\n    })\n  }\n  */\n});\n\n// Examples using Waterline-like syntax\nasync function examples() {\n  // Find all users\n  const response = await api.users.find().execute();\n  const users = response.data;\n  const headers = response.headers;\n\n  // Find users with criteria\n  const activeResponse = await api.users\n    .find({ active: true })\n    .execute();\n  const activeUsers = activeResponse.data;\n\n  // Pagination and sorting\n  const paginatedResponse = await api.users\n    .find()\n    .limit(10)\n    .skip(20)\n    .sort('createdAt DESC')\n    .execute();\n  const paginatedUsers = paginatedResponse.data;\n\n  // Find a single user by ID\n  const userResponse = await api.users.findOne(123);\n  const user = userResponse.data;\n\n  // Create a new user\n  const createResponse = await api.users.create({\n    name: 'John Doe',\n    email: 'john@example.com'\n  });\n  const newUser = createResponse.data;\n  \n  // Access response headers (e.g., for rate limiting info)\n  console.log('Rate limit remaining:', createResponse.headers['x-rate-limit-remaining']);\n\n  // Update an existing user\n  const updateResponse = await api.users.update(123, {\n    name: 'Jane Doe'\n  });\n  const updatedUser = updateResponse.data;\n\n  // Delete a user\n  const deleteResponse = await api.users.destroy(123);\n\n  // Use complex criteria with operators\n  const olderResponse = await api.users\n    .find({ age: { '\u003e': 30 } })\n    .execute();\n  const olderUsers = olderResponse.data;\n}\n```\n\n---\n\n## 🔍 **How It Works**\n\n### 1. **Reads the OpenAPI spec**\nAquaSDK parses your Swagger/OpenAPI JSON definition to understand your API's structure.\n\n### 2. **Preprocesses the spec**\nThe tool resolves circular references and prepares the API definition for SDK generation.\n\n### 3. **Generates Model Classes**\nA class is created for each model in the OpenAPI schema, ensuring proper data handling and validation.\n\n### 4. **Builds Method Chains**\nAquaSDK generates a Waterline-like query syntax for accessing your API’s resources.\n\n### 5. **Creates the SDK**\nA complete SDK is generated, including methods, models, and utility files.\n\n---\n\n## 🚀 **Development and Contribution**\n\nSince AquaSDK is open source, we welcome contributions from developers who wish to improve the tool, add features, or fix bugs.\n\n### How to Contribute\n\n1. Fork the repository and create a new branch.\n2. Make your changes and commit them with clear messages.\n3. Push your changes and submit a pull request with a description of your updates.\n\nWe appreciate all contributions and aim to review pull requests as quickly as possible.\n\n---\n\n## 📄 **License**\n\nAquaSDK is licensed under the **GNU General Public License v3.0 (GPL-3.0)**. See the [LICENSE](LICENSE.md) file for more information.\n\nThe GPL-3.0 license allows you to freely use, modify, and distribute AquaSDK, but requires that you make any derivative works available under the same license. If you distribute AquaSDK, or any derivative works, you must include the source code and provide the GPL license terms.\n\nFor more details, please refer to the [GNU General Public License v3.0](https://www.gnu.org/licenses/gpl-3.0.html).\n\n---\n\nFeel free to use, modify, and contribute to AquaSDK! We hope this tool helps you build better, more efficient integrations with OpenAPI-based APIs. 🚀\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fenricodeleo%2Faquasdk","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fenricodeleo%2Faquasdk","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fenricodeleo%2Faquasdk/lists"}