{"id":13651798,"url":"https://github.com/spailybot/moleculer-auto-openapi","last_synced_at":"2025-04-22T22:32:13.186Z","repository":{"id":198891006,"uuid":"700327601","full_name":"spailybot/moleculer-auto-openapi","owner":"spailybot","description":"Generate openapi scheme for moleculer","archived":false,"fork":false,"pushed_at":"2024-09-22T15:06:37.000Z","size":2230,"stargazers_count":4,"open_issues_count":4,"forks_count":1,"subscribers_count":0,"default_branch":"main","last_synced_at":"2024-11-03T14:04:14.232Z","etag":null,"topics":["moleculer","moleculer-web","openapi"],"latest_commit_sha":null,"homepage":"https://spailybot.github.io/moleculer-auto-openapi/","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":"grinat/moleculer-auto-openapi","license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/spailybot.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}},"created_at":"2023-10-04T11:43:31.000Z","updated_at":"2024-05-09T17:22:48.000Z","dependencies_parsed_at":"2024-05-09T17:44:15.406Z","dependency_job_id":"fdb7c114-c015-4c9d-85fa-e5a7bea425d9","html_url":"https://github.com/spailybot/moleculer-auto-openapi","commit_stats":{"total_commits":116,"total_committers":8,"mean_commits":14.5,"dds":0.2844827586206896,"last_synced_commit":"79db006430dc00eb9f5a6de2d2ab9222b7ae8116"},"previous_names":["thib3113/moleculer-auto-openapi","spailybot/moleculer-auto-openapi"],"tags_count":20,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/spailybot%2Fmoleculer-auto-openapi","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/spailybot%2Fmoleculer-auto-openapi/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/spailybot%2Fmoleculer-auto-openapi/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/spailybot%2Fmoleculer-auto-openapi/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/spailybot","download_url":"https://codeload.github.com/spailybot/moleculer-auto-openapi/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":223906403,"owners_count":17223045,"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":["moleculer","moleculer-web","openapi"],"created_at":"2024-08-02T02:00:52.463Z","updated_at":"2025-04-22T22:32:13.171Z","avatar_url":"https://github.com/spailybot.png","language":"TypeScript","funding_links":[],"categories":["Tools"],"sub_categories":["GraphQL"],"readme":"\u003cdiv align=\"center\"\u003e\n\n[![Moleculer logo](http://moleculer.services/images/banner.png)](https://github.com/moleculerjs/moleculer)\n\u003ch2\u003emoleculer-auto-openapi\u003c/h2\u003e\n\n\u003cp align=\"center\"\u003e\n\u003cimg src=\"https://img.shields.io/badge/Moleculer-3CAFCE.svg?style=flat-square\u0026logo=Moleculer\u0026logoColor=white\" alt=\"Moleculer\" /\u003e\n\u003cimg src=\"https://img.shields.io/badge/TypeScript-3178C6.svg?style=flat-square\u0026logo=TypeScript\u0026logoColor=white\" alt=\"TypeScript\" /\u003e\n\u003ca href=\"https://www.typescriptlang.org/tsconfig#strict\"\u003e\u003cimg src=\"https://img.shields.io/badge/TypeScript-Strict%20Mode-blue\" alt=\"TypeScript Strict Mode\"\u003e\u003c/a\u003e\n\u003c/p\u003e\n\u003cimg src=\"https://img.shields.io/npm/dw/%40spailybot%2Fmoleculer-auto-openapi\" alt=\"GitHub license\" /\u003e\n\u003cimg src=\"https://img.shields.io/github/license/spailybot/moleculer-auto-openapi?style=flat-square\u0026color=5D6D7E\" alt=\"GitHub license\" /\u003e\n\u003ca href=\"https://github.com/spailybot/moleculer-auto-openapi/graphs/contributors\"\u003e\u003cimg src=\"https://img.shields.io/github/contributors/spailybot/moleculer-auto-openapi\" alt=\"contributors\" /\u003e\u003c/a\u003e\n\u003cimg src=\"https://img.shields.io/github/languages/top/spailybot/moleculer-auto-openapi?style=flat-square\u0026color=5D6D7E\" alt=\"GitHub top language\" /\u003e\n\u003ca href=\"https://snyk.io/test/github/spailybot/moleculer-auto-openapi\"\u003e\u003cimg alt=\"Known Vulnerabilities\" src=\"https://snyk.io/test/github/spailybot/moleculer-auto-openapi/badge.svg\" /\u003e\u003c/a\u003e\n\u003ca href=\"https://www.npmjs.com/package/@spailybot/moleculer-auto-openapi\"\u003e\u003cimg alt=\"npm package Vulnerabilities\" src=\"https://img.shields.io/npm/v/@spailybot/moleculer-auto-openapi.svg\" /\u003e\u003c/a\u003e\n\u003ca href=\"https://github.com/spailybot/moleculer-auto-openapi/actions/workflows/CI.yml\"\u003e\u003cimg src=\"https://github.com/spailybot/moleculer-auto-openapi/actions/workflows/CI.yml/badge.svg\" alt=\"CI\"\u003e\u003c/a\u003e\n\u003ca href=\"https://bundlephobia.com/package/@spailybot/moleculer-auto-openapi\"\u003e\u003cimg src=\"https://badgen.net/bundlephobia/tree-shaking/@spailybot/moleculer-auto-openapi\" alt=\"tree shaking supported\"\u003e\u003c/a\u003e\n\u003cimg alt=\"npm bundle size (scoped)\" src=\"https://img.shields.io/bundlephobia/min/%40spailybot/moleculer-auto-openapi\"\u003e\n\u003ca href=\"https://github.com/spailybot/moleculer-auto-openapi/stargazers/\"\u003e\u003cimg src=\"https://img.shields.io/github/stars/spailybot/moleculer-auto-openapi.svg?style=social\u0026label=Star\" alt=\"GitHub stars\"\u003e\u003c/a\u003e\n\u003cimg src=\"https://img.shields.io/badge/module%20type-cjs%2Besm%2Btypes-brightgreen\" alt=\"Module type: CJS+ESM+Types\" /\u003e\n\n\n\u003c/div\u003e\n\n---\n\n\u003e**Why Use OpenAPI:**\n\u003e\n\u003e OpenAPI standardizes and documents RESTful APIs, streamlines development, improves team communication, and automates testing. Moreover, it can be used to generate client SDKs. It allows for a focus on business logic, making it a valuable tool in a microservices environment.\n\n\nThis project is a fork of [moleculer-auto-openapi](https://github.com/grinat/moleculer-auto-openapi) by [grinat](https://github.com/grinat).\n\nBig thanks to [grinat](https://github.com/grinat) for the original work, and also to [everyone who has contributed](https://github.com/grinat/moleculer-auto-openapi/graphs/contributors) to it!\n\n\n## 🌟 Features\n\n- Supports multiple Moleculer-Web servers, allowing API separation\n- `Fastest-Validator` support for direct OpenAPI generation from parameters, complete with examples\n- OpenAPI 3.1 compatibility\n- Cached OpenAPI with efficient regeneration when needed\n- Granular and reusable configuration\n- TypeScript exports of mixin settings and OpenAPI parameters\n- Get your first openapi in less a minute\n\n## 🚀 Getting Started\n\n### 📦 Prerequisites\n\nTo use this library, you must have the [Moleculer](https://github.com/moleculerjs/moleculer) framework installed along with the [Moleculer-Web](https://github.com/moleculerjs/moleculer-web) module. Additionally, the `listAliases` action must be available (which is the default setting).\n\n### 🔧 Installation\n\nInstall the package using your preferred package manager:\n```\nnpm install @spailybot/moleculer-auto-openapi\n```\n\n#### Optional\n\nIf you wish to use a local instance of Swagger UI, install it like this:\n```\nnpm install swagger-ui-dist@^5\n```\n\nFor the full TypeScript autocompletion experience, install the `openapi-types` package in addition to the above:\n```\nnpm install --save-dev openapi-types\n```\n\n---\n\n### 📁 Setting Up Your Service\n\n\u003e **Note:** The following examples use the ESM syntax.\n\u003e\n\u003e Depending on your environment and requirements, you may need to adapt these examples, possibly to the CommonJS (CJS) syntax, or to your specific coding standard.\n\n\u003cbr\u003e\n\n#### Create an OpenApi service\n\n\u003cdetails open\u003e\n    \u003csummary\u003eTypescript\u003c/summary\u003e\n\n```typescript\nimport { OpenApiMixin, type OpenApiMixinSettings, type MoleculerWebTypes } from '@spailybot/moleculer-auto-openapi';\nimport { Service, type ServiceBroker } from 'moleculer';\n\n/**\n * MoleculerWebTypes are typings created from moleculer-web to enhance included typings; their use is totally optional.\n */\n\nexport default class OpenApiService extends Service\u003cOpenApiMixinSettings \u0026 MoleculerWebTypes.RestServiceSettings\u003e {\n    public constructor(public broker: ServiceBroker) {\n        super(broker);\n\n        this.parseServiceSchema({\n            // Choose your preferred name\n            name: 'openapi',\n            mixins: [mixin],\n            settings: {\n                // Set the path as you prefer\n                rest: '/openapi',\n\n                // will set\n                // - ui at /openapi/ui\n                // - json at /openapi/openapi.json\n                // - assets at /openapi/assets/*\n                // - oauth2redirection at /openapi/oauth2-redirect\n                openApiPaths: \"/openapi\",\n                // you cal also do it manually\n                /**\n                 openApiPaths: {\n                 schemaPath: \"/openapi/openapi.json\"\n                 uiPath: \"/openapi/ui\"\n                 oauth2RedirectPath: \"/openapi/oauth2-redirect\"\n                 assetsPath: \"/openapi/assets\"\n                 }\n                 */\n\n                // This will be the root of your document\n                // use it to define some default informations\n                openapi: {\n                    info: {\n                        title: \"My API\",\n                        version: \"0.0.1\"\n                    }\n                }\n            }\n        });\n    }\n}\n```\n\u003cdetails\u003e\n\u003csummary\u003eTypescript without using class\u003c/summary\u003e\n\n```typescript\nimport { OpenApiMixin, type OpenApiMixinSettings, type MoleculerWebTypes } from '@spailybot/moleculer-auto-openapi';\nimport { Service, type ServiceBroker } from 'moleculer';\n\nconst OpenApiService: ServiceSchema\u003cOpenApiMixinSettings \u0026 MoleculerWebTypes.RestServiceSettings\u003e = {\n    // Choose your preferred name\n    name: 'openapi',\n    mixins: [mixin],\n    settings: {\n        // Set the path as you prefer\n        rest: '/openapi',\n\n        // will set\n        // - ui at /openapi/ui\n        // - json at /openapi/openapi.json\n        // - assets at /openapi/assets/*\n        // - oauth2redirection at /openapi/oauth2-redirect\n        openApiPaths: \"/openapi\",\n        // you cal also do it manually\n        /**\n         openApiPaths: {\n         schemaPath: \"/openapi/openapi.json\"\n         uiPath: \"/openapi/ui\"\n         oauth2RedirectPath: \"/openapi/oauth2-redirect\"\n         assetsPath: \"/openapi/assets\"\n         }\n         */\n\n        // This will be the root of your document\n        // use it to define some default informations\n        openapi: {\n            info: {\n                title: \"My API\",\n                version: \"0.0.1\"\n            }\n        }\n    }\n};\nexport default OpenApiService;\n```\n\u003c/details\u003e\n\n\u003c/details\u003e\n\u003cdetails\u003e\n    \u003csummary\u003eJavascript\u003c/summary\u003e\n\n```javascript\nimport { OpenApiMixin } from '@spailybot/moleculer-auto-openapi';\nimport { Service } from 'moleculer';\n\nexport default class OpenApiService extends Service {\n    public constructor(broker) {\n        super(broker);\n\n        this.parseServiceSchema({\n            // Choose your preferred name\n            name: 'openapi',\n            mixins: [OpenApiMixin],\n            settings: {\n                // Set the path as you prefer\n                rest: '/openapi',\n\n                // will set\n                // - ui at /openapi/ui\n                // - json at /openapi/openapi.json\n                // - assets at /openapi/assets/*\n                // - oauth2redirection at /openapi/oauth2-redirect\n                openApiPaths: \"/openapi\",\n                // you cal also do it manually\n                /**\n                openApiPaths: {\n                    schemaPath: \"/openapi/openapi.json\"\n                    uiPath: \"/openapi/ui\"\n                    oauth2RedirectPath: \"/openapi/oauth2-redirect\"\n                    assetsPath: \"/openapi/assets\"\n                }\n                */\n\n                // This will be the root of your document\n                // use it to define some default informations\n                openapi: {\n                    info: {\n                        title: \"My API\",\n                        version: \"0.0.1\"\n                    }\n                }\n            }\n        });\n    }\n}\n```\n\u003cdetails\u003e\n    \u003csummary\u003eJavascript without using class\u003c/summary\u003e\n\n````javascript\nimport { OpenApiMixin } from '@spailybot/moleculer-auto-openapi';\n\nconst OpenApiService = {\n  // Choose your preferred name\n  name: 'openapi',\n  mixins: [OpenApiMixin],\n  settings: {\n        // Set the path as you prefer\n        rest: '/openapi',\n\n        // will set\n        // - ui at /openapi/ui\n        // - json at /openapi/openapi.json\n        // - assets at /openapi/assets/*\n        // - oauth2redirection at /openapi/oauth2-redirect\n        openApiPaths: \"/openapi\",\n        // you cal also do it manually\n        /**\n         openApiPaths: {\n         schemaPath: \"/openapi/openapi.json\"\n         uiPath: \"/openapi/ui\"\n         oauth2RedirectPath: \"/openapi/oauth2-redirect\"\n         assetsPath: \"/openapi/assets\"\n         }\n         */\n\n        // This will be the root of your document\n        // use it to define some default informations\n        openapi: {\n            info: {\n                title: \"My API\",\n                version: \"0.0.1\"\n            }\n        }\n}\n};\nexport default OpenApiService;\n````\n\u003c/details\u003e\n\u003cdetails\u003e\n    \u003csummary\u003eJavascript using CJS\u003c/summary\u003e\n\n````javascript\nconst OpenApiMixin = require('@spailybot/moleculer-auto-openapi');\n// or\n// const { OpenApiMixin } = require('@spailybot/moleculer-auto-openapi');\n\nmodule.exports = {\n    // Choose your preferred name\n    name: \"openapi\",\n    mixins: [OpenApiMixin],\n    settings: {\n        // Set the path as you prefer\n        rest: '/openapi',\n\n        // will set\n        // - ui at /openapi/ui\n        // - json at /openapi/openapi.json\n        // - assets at /openapi/assets/*\n        // - oauth2redirection at /openapi/oauth2-redirect\n        openApiPaths: \"/openapi\",\n        // you cal also do it manually\n        /**\n         openApiPaths: {\n         schemaPath: \"/openapi/openapi.json\"\n         uiPath: \"/openapi/ui\"\n         oauth2RedirectPath: \"/openapi/oauth2-redirect\"\n         assetsPath: \"/openapi/assets\"\n         }\n         */\n\n        // This will be the root of your document\n        // use it to define some default informations\n        openapi: {\n            info: {\n                title: \"My API\",\n                version: \"0.0.1\"\n            }\n        }\n    }\n};\n\n````\n\u003c/details\u003e\n\u003c/details\u003e\n\nYou can find detailed information about all the settings of the mixin in the [technical documentation](https://spailybot.github.io/moleculer-auto-openapi/types/index.OpenApiMixinSettings.html).\n\n#### Update your moleculer-web service\n\n\u003cdetails open\u003e\n    \u003csummary\u003eTypescript\u003c/summary\u003e\n\n```typescript\nimport type { ApiSettingsSchemaOpenApi } from '@spailybot/moleculer-auto-openapi';\nimport ApiGateway from \"moleculer-web\";\nimport { Service, type ServiceBroker } from 'moleculer';\n\n/**\n * Note that ApiSettingsSchemaOpenApi is a re-export of ApiSettingsSchema because moleculer-web doesn't allow to extend it.\n */\n\nexport default class WebApiService extends Service\u003cApiSettingsSchemaOpenApi\u003e {\n    public constructor(public broker: ServiceBroker) {\n        super(broker);\n\n        this.parseServiceSchema({\n            name: \"api\",\n            mixins: [mixin],\n            settings: {\n                // Place other settings here\n                openapi: {\n                    // Define an OpenAPI specification that will be applied to all routes of this api\n                },\n                routes: [\n                    // Place additional route configurations here\n                    {\n                        openapi: {\n                            // Define an OpenAPI specification that will apply to all aliases within this route\n                        },\n                        path: '/openapi',\n                        aliases: {\n                            'GET /openapi.json': 'openapi.generateDocs',\n                            'GET /ui': 'openapi.ui',\n                            'GET /assets/:file': 'openapi.assets',\n                            'GET /oauth2-redirect': 'openapi.oauth2Redirect',\n                        },\n                    },\n                    // To use autoAliases, refer to the following configuration\n                    // {\n                    //     path: '/openapi',\n                    //     whitelist: ['openapi.*'],\n                    //     autoAliases: true\n                    // }\n\n                ]\n                // Insert other settings here\n            }\n        });\n    }\n}\n```\n\u003c/details\u003e\n\u003cdetails\u003e\n    \u003csummary\u003eJavascript\u003c/summary\u003e\n\n```javascript\nimport ApiGateway from \"moleculer-web\";\nimport { Service } from 'moleculer';\n\nexport default class WebApiService extends Service {\n    public constructor(broker) {\n        super(broker);\n\n        this.parseServiceSchema({\n            name: \"api\",\n            mixins: [mixin],\n            settings: {\n                // Place other settings here\n                openapi: {\n                    // Define an OpenAPI specification that will be applied to all routes of this api\n                },\n                routes: [\n                    // Place additional route configurations here\n                    {\n                        openapi: {\n                            // Define an OpenAPI specification that will apply to all aliases within this route\n                        },\n                        path: '/openapi',\n                        aliases: {\n                            'GET /openapi.json': 'openapi.generateDocs',\n                            'GET /ui': 'openapi.ui',\n                            'GET /assets/:file': 'openapi.assets',\n                            'GET /oauth2-redirect': 'openapi.oauth2Redirect',\n                        },\n                    },\n                    // To use autoAliases, refer to the following configuration\n                    // {\n                    //     path: '/openapi',\n                    //     whitelist: ['openapi.*'],\n                    //     autoAliases: true\n                    // }\n\n                ]\n                // Insert other settings here\n            }\n        });\n    }\n}\n```\n\u003c/details\u003e\n\n#### Launch Your Project\n\nYour setup is now complete.\n\nTo view your API documentation via Swagger UI, you can navigate to `http://127.0.0.1/openapi/ui` in your web browser (adjust the URL according to your configuration).\n\n#### What's Next?\n\nWith your project now up and running, there are several resources available to help you develop further:\n\n1. **Examples:** Check out the examples in the [examples](https://github.com/spailybot/moleculer-auto-openapi/tree/main/examples) folder. These provide practical code snippets and usage scenarios that can help you understand how to leverage this tool in various situations.\n2. **Wiki:** Visit our [Wiki](https://github.com/spailybot/moleculer-auto-openapi/wiki) for a comprehensive guide on different features, advanced topics, and best practices.\n3. **FAQs:** The [Frequently Asked Questions](https://github.com/spailybot/moleculer-auto-openapi/wiki/FAQ) section can provide quick answers to common queries and issues others have encountered.\n\nRemember, the journey of mastering any tool involves experimentation, learning from examples, reading documentation, and continuous practice. Happy coding!\n\n### 📝 TODO\n\n- $$oa\n  - allow to define a ref, and use the ref instead of creating a new one\n  - allow to define a \"to ref\", and create the ref with this name\n  - allow to define examples\n- investigate the needs of requestBodyAndResponseBodyAreSameOnMethods / requestBodyAndResponseBodyAreSameDescription\n- support multiple openapi version on generator ? (will need converters)\n\n### ⚠️ Known Limitations\n- Functions used directly in parameters (e.g., dynamic `default`) might not execute reliably or as expected, and will be called without arguments.\n\n## 📄 License\n\nThis project is protected under the [MIT](https://choosealicense.com/licenses/mit/) License. For more details, refer to the [LICENSE](https://github.com/spailybot/moleculer-auto-openapi/blob/main/LICENSE) file.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fspailybot%2Fmoleculer-auto-openapi","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fspailybot%2Fmoleculer-auto-openapi","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fspailybot%2Fmoleculer-auto-openapi/lists"}