@ublitzjs/openapi package for typed documentation

Supported in - @ublitzjs/core, @ublitzjs/router

serverExtension

This function lets you decorate "server" object, given by "extendApp" from "core" package, which provide you with easy control over your docs

import { serverExtension } from "@ublitz.js/openapi";
import { extendApp } from "@ublitzjs/core";
import { App } from "uWebSockets.js";
var server = extendApp(
  App(),
  serverExtension({
    info: { title: "Your server", version: "0.1.0" },
    openapi: "3.1.0",
    /**
     * and components
     * and externalDocs
     * and security
     * and servers
     * and tags
     * and webhooks
     */
  })
);
/**
 * then you define some schemas and routes
 * Examples are below in readme.
 * So several routes later:
 */
var BUILD_OPENAPI_TO_JSON = false as boolean;

if (BUILD_OPENAPI_TO_JSON === true)
  server.buildOpenApi(
    /*path*/ "openapi.json",
    /*exit from node.js (better for performance, if app will be compiled afterwards without these schemas)*/ true
  );
await server.serveOpenApi(
  /*url (but it is fully working ONLY by http://localhost:port/docs/ with last slash, sorry)*/ "/docs",
  {
    // whether to use buildOpenApi before starting server. Mostly useless. But if development - ok
    build: false,
    /**same as in @ublitzjs/static package */
    clearMimes: true,
    path: "openapi.json",
    /**OPTIONAL, but if you moved UI somewhere - use this */
    uiPath: "node_modules/@ublitzjs/openapi/ui",
  }
);
server.listen(9001, () => {});

routeAddOns, methodAddOns, routePlugin, RouterPlugin

First two - typescript interfaces, second too - function for registrating openapi.

server.route from @ublitzjs/core

import { routePlugin } from "@ublitz.js/openapi";
import { DeclarativeResponse, type onlyHttpMethods } from "@ublitzjs/core";

server.route<onlyHttpMethods, methodAddOns>(
  {
    method: "get",
    controller: new DeclarativeResponse()
      .writeHeaders({
        "Content-Type": "text/plain",
        "Last-Modified": new Date().toUTCString(),
      })
      .end("hello"),
    path: "/",
    // here are used comments, designated for clearing unwanted code by @ublitzjs/dev-comments
    /*_START_DEV_*/ openapi: {
      description: "hello",
      deprecated: false,
      produces: ["text/plain"],
      responses: {
        200: {
          description: "usual response",
          headers: {
            "Last-Modified": {
              description: "for caching",
              schema: { type: "string" },
            },
          },
          content: {
            "text/plain": { schema: { type: "string" } },
          },
        },
      },
    },
    /*_END_DEV_*/
  },
  // this function uses your openapi
  // If you build your project with @ublitzjs/dev-comments, then you should mark this plugin
  /*_START_DEV_*/ [routePlugin] /*_END_DEV_*/
);

ExtendedRouter with extPaths from @ublitzjs/router - go here

Optimizing performance using @ublitzjs/dev-comments

it is a good practise to clean openapi from project using @ublitzjs/dev-comments after building it into openapi.json file. So you might want to create a script, which

1. runs your app for the first time with a specific setting for calling buildOpenApi("openapi.json", true) and quits from node.js
2. then runs minifyFile OR minifyFolder (depending on your project size) for removing unwanted openapi docs
3. runs esbuild for bundling your project into single file FROM newly created direcory or file by dev-comments
4. removes directory or file, created by dev-comments This script will help you free several (or LOTS OF) kilobytes of ram, by ensuring that openapi.json is always static and doesn't need to be loaded