npm package: @spectrajs/swagger
Description: Swagger integration for Spectra
Author: metebykl
Latest version: 0.14.1

# @spectrajs/swagger

[![codecov](https://codecov.io/gh/metebykl/spectra/graph/badge.svg)](https://codecov.io/gh/metebykl/spectra)
[![GitHub Workflow Status](https://img.shields.io/github/actions/workflow/status/metebykl/spectra/ci.yml?branch=main)](https://github.com/metebykl/spectra/actions)
[![License](https://img.shields.io/github/license/metebykl/spectra)](https://github.com/metebykl/spectra/blob/main/LICENSE)
[![npm](https://img.shields.io/npm/v/@spectrajs/swagger.svg)](https://www.npmjs.com/package/@spectrajs/swagger)
[![npm](https://img.shields.io/npm/d18m/@spectrajs/swagger.svg)](https://www.npmjs.com/package/@spectrajs/swagger)
[![Bundle Size](https://img.shields.io/bundlephobia/min/@spectrajs/swagger)](https://bundlephobia.com/result?p=@spectrajs/swagger)

A Spectra plugin for serving [Swagger (OpenAPI v3)](https://swagger.io/specification)
schemas, which are automatically generated from your routes.

## Installation

```sh
npm install @spectrajs/swagger
```

## Documentation

The documentation is available [here](../../docs/plugins/swagger.md).

## Usage

```ts
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](https://spec.openapis.org/oas/v3.1.0.html) specification.

```ts
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](https://spec.openapis.org/oas/v3.1.0.html)
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](https://swagger.io/tools/swagger-ui) page documenting your application.

```ts
type SwaggerUIOptions = Omit<
  Partial<SwaggerUIConfigOptions>,
  "dom_id" | "dom_node" | "url" | "urls" | "spec"
> & {
  url: string;
  title?: string;
  version?: string;
};
```

### swaggerEditor

Serve [Swagger Editor](https://editor.swagger.io) on a specific route.

```ts
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](LICENSE) for more information.