XyPriss Swagger Plugin

The XyPriss Swagger Plugin is a high-performance auto-documentation tool for the XyPriss ecosystem. It automatically generates OpenAPI 3.0 specifications by introspecting the XyPriss route registry and serves a beautiful Swagger UI through an isolated auxiliary server.

Auto-Generation

Automatically extracts routes, methods, and parameters.

Isolated Serving

Hosted on an auxiliary server for maximum security.

Zero-Trust Ready

Respects all XyPriss security layers and guards.

Installation

Install the plugin via XFPM:

bash

xfpm add xypriss-swagger --verify

Usage

Register the Plugin

Import and register the SwaggerPlugin in your server options:

typescript

import { SwaggerPlugin } from "xypriss-swagger";
import { createServer } from "xypriss";

const server = createServer({
    plugins: {
        register: [
            SwaggerPlugin({
                port: 7070, // Port for the documentation server
                path: "/docs", // Path to access the Swagger UI
                title: "My API", // Documentation title
                version: "1.0.0", // API Version
            }),
        ],
    },
});

server.start();

Configure Plugin Access

Ensure the plugin is authorized in your xypriss.config.jsonc:

jsonc

{
    "$internal": {
        "xypriss-swagger": {
            "__meta__": {
                "path": "ROOT://",
            },
            "__xfs__": {
                "path": "CWD://",
            },
            "permissions": {
                "allowedHooks": [
                    "XHS.HOOK.HTTP.REQUEST",
                    "XHS.PERM.SECURITY.SENSITIVE_DATA",
                    "XHS.HOOK.LIFECYCLE.REGISTER",
                    "XHS.HOOK.LIFECYCLE.SERVER_START",
                    "XHS.PERM.OPS.AUXILIARY_SERVER",
                    "XHS.PERM.SECURITY.CONFIGS",
                ],
                "policy": "allow",
            },
        },
    },
}

Configuration Options

Option	Type	Default	Description
port	number	7070	The port for the auxiliary Swagger server.
path	string	"/docs"	The base path for documentation UI.
title	string	"API Documentation"	Title displayed in Swagger UI.

Security & Identity

Developer Identity

Developer ID: ed25519:a58b17a3e46302dd3ae5538bc9b8b991c57f4c5fe2e7d8ac41803de818d947f4
This plugin is cryptographically signed. Always verify the signature during installation.

Route Metadata

Customize documentation for individual routes by adding metadata:

typescript

server.get(
    "/users/:id",
    (req, res) => { /* ... */ },
    {
        meta: {
            summary: "Get user by ID",
            tags: ["Users"],
            openapi: {
                responses: {
                    "200": { description: "User found" },
                },
            },
        },
    },
);

Xyphra Logger

Next: High-performance logging with Xyphra.