@spectrajs/swagger

A Spectra plugin for serving Swagger (OpenAPI v3) schemas, which are automatically generated from your routes.

Installation

npm install @spectrajs/swagger

Documentation

The documentation is available here.

Usage

import { Spectra } from "@spectrajs/core";
import { describeRoute, openAPISpecs, swaggerUI } from "@spectrajs/swagger";

const app = new Spectra();

app.get(
  "/",
  describeRoute({
    description: "Greet the user",
    responses: {
      200: {
        description: "Successful greeting response",
        content: {
          "text/plain": {
            example: "Hi Spectra!",
          },
        },
      },
    },
  }),
  (c) => {
    const name = c.req.query("name");
    return c.text(`Hi ${name}!`);
  }
);

// Generate the OpenAPI specification
app.use(
  "/openapi",
  openAPISpecs(app, {
    documentation: {
      info: {
        title: "Spectra",
        version: "1.0.0",
        description: "Example API",
      },
      servers: [
        {
          url: "http://localhost:8282",
          description: "Example Server",
        },
      ],
    },
  })
);

// Serve the OpenAPI specification with Swagger UI
app.use("/swagger", swaggerUI({ url: "/openapi" }));

API

describeRoute

Add a description to a route, which will be included in the OpenAPI specification.

interface OpenAPIOperation {
  summary?: string;
  description?: string;
  tags?: string[];
  responses: OpenAPIResponses;
  operationId?: string;
  parameters?: OpenAPIParameter[];
  requestBody?: OpenAPIRequestBody;
  callbacks?: Record<string, OpenAPIPathItem>;
  deprecated?: boolean;
  security?: OpenAPISecurityRequirement[];
  servers?: OpenAPIServer[];
}

openAPISpecs

Generate an OpenAPI specification for your application.

documentation?: OpenAPIDocument

Customize the documentation.

exclude?: string[]

Paths to exclude from the documentation.

excludeMethods?: HttpMethod[]

Methods to exclude from the documentation.

excludeTags?: string[]

Tags to exclude from the documentation.

swaggerUI

Generate a Swagger UI page documenting your application.

type SwaggerUIOptions = Omit<
  Partial<SwaggerUIConfigOptions>,
  "dom_id" | "dom_node" | "url" | "urls" | "spec"
> & {
  url: string;
  title?: string;
  version?: string;
};

swaggerEditor

Serve Swagger Editor on a specific route.

type SwaggerEditorOptions = Omit<
  Partial<SwaggerUIConfigOptions>,
  "dom_id" | "dom_node" | "url" | "urls" | "spec" | "presets"
> & {
  title?: string;
  version?: string;
};

License

Distributed under the MIT License. See LICENSE for more information.