@spailybot/moleculer-auto-openapi - v2.0.0

moleculer-auto-openapi

Why Use OpenAPI:

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.

This project is a fork of moleculer-auto-openapi by grinat.

Big thanks to grinat for the original work, and also to everyone who has contributed to it!

⚠️ Moleculer 0.14 users: versions up to 1.4.x support Moleculer 0.14.x. Starting with 2.0.0, this library targets Moleculer 0.15.x only (with moleculer-web 0.11.x), which requires Node.js ≥ 22. If you're on Moleculer 0.14, install the dedicated dist-tag to keep getting fixes:
npm install @spailybot/moleculer-auto-openapi@moleculer-0.14-backports

🌟 Features

Supports multiple Moleculer-Web servers, allowing API separation
Fastest-Validator integration for direct OpenAPI generation from action parameters
Rich OpenAPI 3.1 metadata support with $$oa metaparams and global $$* shortcuts ($$title, $$description, $$default, $$examples, etc.)
Schema and parameter reference overrides ($ref) directly within parameter definitions
Advanced and customizable requestBody configuration
Cached OpenAPI generation with efficient on-demand regeneration
Granular and reusable configuration hierarchy
Full TypeScript typings for mixin settings, route schemas, and OpenAPI parameters
Get your first OpenAPI documentation in less than a minute

🚀 Getting Started

📦 Prerequisites

This library requires:

Moleculer 0.15.x (installed as a peer dependency)
Moleculer-Web 0.11.x
Node.js ≥ 22
The listAliases action must be available (which is the default setting).

Migrating from Moleculer 0.14 / moleculer-web 0.10? moleculer-web 0.11 ships path-to-regexp 8: update your route aliases — optional parameters :name? become {/:name} and wildcards *foo become :foo*. In multipart (file upload) aliases, form fields now land in ctx.params (previously ctx.meta) and the file in ctx.stream.

🔧 Installation

Install the package using your preferred package manager:

npm install @spailybot/moleculer-auto-openapi

Optional

If you wish to use a local instance of Swagger UI, install it like this:

npm install swagger-ui-dist@^5

For the full TypeScript autocompletion experience, install the openapi-types package in addition to the above:

npm install --save-dev openapi-types

📁 Setting Up Your Service

Note: The following examples use the ESM syntax.

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.

Create an OpenApi service

Typescript

import { OpenApiMixin, type OpenApiMixinSettings, type MoleculerWebTypes } from '@spailybot/moleculer-auto-openapi';
import { Service, type ServiceBroker } from 'moleculer';

/**
 * MoleculerWebTypes are typings created from moleculer-web to enhance included typings; their use is totally optional.
 */

export default class OpenApiService extends Service<OpenApiMixinSettings & MoleculerWebTypes.RestServiceSettings> {
    public constructor(public broker: ServiceBroker) {
        super(broker);

        this.parseServiceSchema({
            // Choose your preferred name
            name: 'openapi',
            mixins: [OpenApiMixin],
            settings: {
                // Set the path as you prefer
                rest: '/openapi',

                // will set
                // - ui at /openapi/ui
                // - json at /openapi/openapi.json
                // - assets at /openapi/assets/*
                // - oauth2redirection at /openapi/oauth2-redirect
                openApiPaths: "/openapi",
                // you cal also do it manually
                /**
                 openApiPaths: {
                 schemaPath: "/openapi/openapi.json"
                 uiPath: "/openapi/ui"
                 oauth2RedirectPath: "/openapi/oauth2-redirect"
                 assetsPath: "/openapi/assets"
                 }
                 */

                // This will be the root of your document
                // use it to define some default informations
                openapi: {
                    info: {
                        title: "My API",
                        version: "0.0.1"
                    }
                }
            }
        });
    }
}

Typescript without using class

import { OpenApiMixin, type OpenApiMixinSettings, type MoleculerWebTypes } from '@spailybot/moleculer-auto-openapi';
import { Service, type ServiceBroker } from 'moleculer';

const OpenApiService: ServiceSchema<OpenApiMixinSettings & MoleculerWebTypes.RestServiceSettings> = {
    // Choose your preferred name
    name: 'openapi',
    mixins: [OpenApiMixin],
    settings: {
        // Set the path as you prefer
        rest: '/openapi',

        // will set
        // - ui at /openapi/ui
        // - json at /openapi/openapi.json
        // - assets at /openapi/assets/*
        // - oauth2redirection at /openapi/oauth2-redirect
        openApiPaths: "/openapi",
        // you cal also do it manually
        /**
         openApiPaths: {
         schemaPath: "/openapi/openapi.json"
         uiPath: "/openapi/ui"
         oauth2RedirectPath: "/openapi/oauth2-redirect"
         assetsPath: "/openapi/assets"
         }
         */

        // This will be the root of your document
        // use it to define some default informations
        openapi: {
            info: {
                title: "My API",
                version: "0.0.1"
            }
        }
    }
};
export default OpenApiService;

Javascript

import { OpenApiMixin } from '@spailybot/moleculer-auto-openapi';
import { Service } from 'moleculer';

export default class OpenApiService extends Service {
    public constructor(broker) {
        super(broker);

        this.parseServiceSchema({
            // Choose your preferred name
            name: 'openapi',
            mixins: [OpenApiMixin],
            settings: {
                // Set the path as you prefer
                rest: '/openapi',

                // will set
                // - ui at /openapi/ui
                // - json at /openapi/openapi.json
                // - assets at /openapi/assets/*
                // - oauth2redirection at /openapi/oauth2-redirect
                openApiPaths: "/openapi",
                // you cal also do it manually
                /**
                openApiPaths: {
                    schemaPath: "/openapi/openapi.json"
                    uiPath: "/openapi/ui"
                    oauth2RedirectPath: "/openapi/oauth2-redirect"
                    assetsPath: "/openapi/assets"
                }
                */

                // This will be the root of your document
                // use it to define some default informations
                openapi: {
                    info: {
                        title: "My API",
                        version: "0.0.1"
                    }
                }
            }
        });
    }
}

Javascript without using class

import { OpenApiMixin } from '@spailybot/moleculer-auto-openapi';

const OpenApiService = {
  // Choose your preferred name
  name: 'openapi',
  mixins: [OpenApiMixin],
  settings: {
        // Set the path as you prefer
        rest: '/openapi',

        // will set
        // - ui at /openapi/ui
        // - json at /openapi/openapi.json
        // - assets at /openapi/assets/*
        // - oauth2redirection at /openapi/oauth2-redirect
        openApiPaths: "/openapi",
        // you cal also do it manually
        /**
         openApiPaths: {
         schemaPath: "/openapi/openapi.json"
         uiPath: "/openapi/ui"
         oauth2RedirectPath: "/openapi/oauth2-redirect"
         assetsPath: "/openapi/assets"
         }
         */

        // This will be the root of your document
        // use it to define some default informations
        openapi: {
            info: {
                title: "My API",
                version: "0.0.1"
            }
        }
}
};
export default OpenApiService;

Javascript using CJS

const OpenApiMixin = require('@spailybot/moleculer-auto-openapi');
// or
// const { OpenApiMixin } = require('@spailybot/moleculer-auto-openapi');

module.exports = {
    // Choose your preferred name
    name: "openapi",
    mixins: [OpenApiMixin],
    settings: {
        // Set the path as you prefer
        rest: '/openapi',

        // will set
        // - ui at /openapi/ui
        // - json at /openapi/openapi.json
        // - assets at /openapi/assets/*
        // - oauth2redirection at /openapi/oauth2-redirect
        openApiPaths: "/openapi",
        // you cal also do it manually
        /**
         openApiPaths: {
         schemaPath: "/openapi/openapi.json"
         uiPath: "/openapi/ui"
         oauth2RedirectPath: "/openapi/oauth2-redirect"
         assetsPath: "/openapi/assets"
         }
         */

        // This will be the root of your document
        // use it to define some default informations
        openapi: {
            info: {
                title: "My API",
                version: "0.0.1"
            }
        }
    }
};

You can find detailed information about all the settings of the mixin in the technical documentation.

Update your moleculer-web service

Typescript

import type { ApiSettingsSchemaOpenApi } from '@spailybot/moleculer-auto-openapi';
import ApiGateway from "moleculer-web";
import { Service, type ServiceBroker } from 'moleculer';

/**
 * Note that ApiSettingsSchemaOpenApi is a re-export of ApiSettingsSchema because moleculer-web doesn't allow to extend it.
 */

export default class WebApiService extends Service<ApiSettingsSchemaOpenApi> {
    public constructor(public broker: ServiceBroker) {
        super(broker);

        this.parseServiceSchema({
            name: "api",
            mixins: [ApiGateway],
            settings: {
                // Place other settings here
                openapi: {
                    // Define an OpenAPI specification that will be applied to all routes of this api
                },
                routes: [
                    // Place additional route configurations here
                    {
                        openapi: {
                            // Define an OpenAPI specification that will apply to all aliases within this route
                        },
                        path: '/openapi',
                        aliases: {
                            'GET /openapi.json': 'openapi.generateDocs',
                            'GET /ui': 'openapi.ui',
                            'GET /assets/:file': 'openapi.assets',
                            'GET /oauth2-redirect': 'openapi.oauth2Redirect',
                        },
                    },
                    // To use autoAliases, refer to the following configuration
                    // {
                    //     path: '/openapi',
                    //     whitelist: ['openapi.*'],
                    //     autoAliases: true
                    // }

                ]
                // Insert other settings here
            }
        });
    }
}

Javascript

import ApiGateway from "moleculer-web";
import { Service } from 'moleculer';

export default class WebApiService extends Service {
    public constructor(broker) {
        super(broker);

        this.parseServiceSchema({
            name: "api",
            mixins: [ApiGateway],
            settings: {
                // Place other settings here
                openapi: {
                    // Define an OpenAPI specification that will be applied to all routes of this api
                },
                routes: [
                    // Place additional route configurations here
                    {
                        openapi: {
                            // Define an OpenAPI specification that will apply to all aliases within this route
                        },
                        path: '/openapi',
                        aliases: {
                            'GET /openapi.json': 'openapi.generateDocs',
                            'GET /ui': 'openapi.ui',
                            'GET /assets/:file': 'openapi.assets',
                            'GET /oauth2-redirect': 'openapi.oauth2Redirect',
                        },
                    },
                    // To use autoAliases, refer to the following configuration
                    // {
                    //     path: '/openapi',
                    //     whitelist: ['openapi.*'],
                    //     autoAliases: true
                    // }

                ]
                // Insert other settings here
            }
        });
    }
}

Launch Your Project

Your setup is now complete.

To 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).

What's Next?

With your project now up and running, there are several resources available to help you develop further:

Examples: Check out the examples in the examples folder. These provide practical code snippets and usage scenarios that can help you understand how to leverage this tool in various situations.
Wiki: Visit our Wiki for a comprehensive guide on different features, advanced topics, and best practices.
FAQs: The Frequently Asked Questions section can provide quick answers to common queries and issues others have encountered.

Remember, the journey of mastering any tool involves experimentation, learning from examples, reading documentation, and continuous practice. Happy coding!

📝 TODO

Allow defining a "to ref" to create named references
Investigate needs of requestBodyAndResponseBodyAreSameOnMethods / requestBodyAndResponseBodyAreSameDescription
Support multiple OpenAPI versions on generator (with version-specific converters)

⚠️ Known Limitations

Functions used directly in parameters (e.g., dynamic default) might not execute reliably or as expected, and will be called without arguments.

📄 License

This project is protected under the MIT License. For more details, refer to the LICENSE file.