Installation

Thanks to AxiSpark.js, you can easily install the OpenApi Plugin in your project. Follow the steps below to get started.

Prerequisites

Before using the OpenApi Plugin, you need to have the HTTP Plugin installed and configured in your project. The OpenApi Plugin relies on the HTTP Plugin to extract information about your API endpoints and to expose the OpenAPI documentation as REST endpoints. Please, check the HTTP Plugin documentation

1. Install the OpenApi Plugin

You can use npm or any other package manager to install the OpenApi Plugin. Run the following command in your project directory:

npm install @axispark/openapi

2. Import the OpenApi Plugin

Once the installation is complete, you can import the OpenApi Plugin into your project. Add the following line to your code:

import { AxiSparkFactory } from '@axisparkjs/core';
import { OpenApiPlugin, OpenApiPluginOptionsFactory } from '@axisparkjs/openapi';

export const app = AxiSparkFactory.create({
    ...
});

app.use(OpenApiPlugin, OpenApiPluginOptionsFactory.create({
    // Configuration options
}));

3. Configure the OpenApi Plugin

OpenApi Plugin offers a OpenApiPluginOptionsFactory class that allows you to configure the plugin with various options. The OpenApiPluginOptionsFactory.create() method accepts an object with the following properties:

/**
 * Interface representing the options for configuring the OpenAPI plugin.
 */
export interface OpenApiPluginOptions extends PluginOptions {
    /**
     * Information about the API.
     */
    info: {
        title: string;
        version: string;
        description?: string;
        termsOfService?: string;
        contact?: {
            name?: string;
            url?: string;
            email?: string;
        };
        license?: {
            name: string;
            url?: string;
            identifier?: string;
        };
        summary?: string;
        externalDocs?: {
            description?: string;
            url: string;
        };
        tags?: {
            name: string;
            description?: string;
        }[];
        servers?: {
            url: string;
            description?: string;
        }[];
    };
    /**
     * If true, the OpenAPI plugin will use the global prefix for the documentation routes. If false, it will not use the global prefix.
     */
    globalPrefix?: boolean;
    /**
     * Url path for the OpenAPI documentation.
     */
    docsUrl?: string;
    /**
     * Url path for the OpenAPI JSON document.
     */
    jsonDocumentUrl?: string;
    /**
     * Url path for the OpenAPI YAML document.
     */
    yamlDocumentUrl?: string;
    /**
     * If true, the OpenAPI plugin will expose the JSON document as a REST endpoint.
     */
    exposeJson?: boolean;
    /**
     * If true, the OpenAPI plugin will expose the YAML document as a REST endpoint.
     */
    exposeYaml?: boolean;
}