Fluid-OAS

Declaratively build type-safe HTTP APIs in TypeScript through the OpenAPI specification.

Installation

With npm:

npm install fluid-oas --save-dev

With Bun:

bun add --development fluid-oas

Visit the docs here

1. Overview
   • Example Usage
2. Schema Design
   • Primitives
   • Objects
   • Arrays

Overview

Fluid-OAS is an embedded, completely functional domain specific language for expressing type-safe HTTP APIs written in TypeScript through the OpenAPI specification.

• No dependencies, use as is.
• Write the most complex OpenAPI specification you want, use whatever framework you want.
• Focus on core business logic, design systems in an API-first manner.
• Leverage TypeScript's advanced type-system to get autocomplete and compile-time checks for building your OpenAPI specification.
• Significantly reduce the amount of boilerplate JSON your team has to write.

Example Usage

import { Contact, Info, OpenApiV3, Operation, Union, String, Example, Null, Object, Responses, Response, MediaType, PathItem, Parameter, Path, OpenApiOperation } from "fluid-oas";

const info = Info.addTitle("My API")
  .addVersion("1.0.0")
  .addDescription("Example description.")
  .addSummary("Example Summary")
  .addContact(
    // Add contact information if needed.
    Contact.addEmail("[email protected]")
      .addName("Your Name.")
      .addUrl("https://domain.com")
  );

// Example schemas
const nameSchema = Union(
  String.addMinLength(1)
    .addMaxLength(10)
    .addExample(Example.addValue("John"))
    .addDescription("Name of the person."),
  Null
);

const uuidSchema = String.addFormat("uuid")
  .addExample("5e91507e-5630-4efd-9fd4-799178870b10") // Examples are supported but are deprecated as of 3.0.0
  .addDescription("Unique identifer");

const userSchema = Object.addProperties({
  firstName: nameSchema,
  lastName: nameSchema,
  id: uuidSchema,
}).addRequired(["id"]); // id is required an should match the id key in the Object.

const errorSchema = Object.addProperties({
  message: String.addReadOnly(true),
});

const getUserResponses = Responses({
  200: Response.addDescription("Successfully Retrieved User!").addContents({
    "application/json": MediaType.addSchema(userSchema),
  }),
  401: Response.addDescription("Failed to retrieve user!").addContents({
    "application/json": MediaType.addSchema(errorSchema),
  }),
});

// Declare Path Items
const getUser = PathItem.addMethod({
  get: addBearerAuthToRoute(Operation).addResponses(getUserResponses)
});

function addBearerAuthToRoute(op: OpenApiOperation): OpenApiOperation {
  return op.addParameters([Parameter.header.addIn("header").addName("bearer")])
}

// Register Paths
const path = Path.addEndpoints({ "/user/{id}": getUser })

const oas = OpenApiV3.addOpenApiVersion("3.1.1").addInfo(info).addPaths(path);

// Write OAS Spec
oas.writeOASSync();

{
  "openapi": "3.1.1",
  "info": {
    "summary": "Example Summary",
    "description": "Example description.",
    "title": "My API",
    "version": "1.0.0",
    "contact": {
      "name": "Your Name.",
      "url": "https://domain.com",
      "email": "[email protected]"
    }
  },
  "paths": {
    "/api/v1/user/{id}": {
      "get": {
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "description": "Unique identifer",
              "example": "5e91507e-5630-4efd-9fd4-799178870b10",
              "format": "uuid",
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Successfully Retrieved User!",
            "content": {
              "application/json": {
                "schema": {
                  "properties": {
                    "firstName": {
                      "type": ["string", "null"],
                      "description": "Name of the person.",
                      "example": {
                        "value": "John"
                      },
                      "minLength": 1,
                      "maxLength": 10
                    },
                    "lastName": {
                      "type": ["string", "null"],
                      "description": "Name of the person.",
                      "example": {
                        "value": "John"
                      },
                      "minLength": 1,
                      "maxLength": 10
                    },
                    "id": {
                      "description": "Unique identifer",
                      "example": "5e91507e-5630-4efd-9fd4-799178870b10",
                      "format": "uuid",
                      "type": "string"
                    }
                  },
                  "required": ["id"],
                  "type": "object"
                }
              }
            }
          },
          "401": {
            "description": "Failed to retrieve user!",
            "content": {
              "application/json": {
                "schema": {
                  "properties": {
                    "message": {
                      "readOnly": true,
                      "type": "string"
                    }
                  },
                  "type": "object"
                }
              }
            }
          }
        }
      }
    }
  }
}

Schemas

Primitive Data types

All schemas are reflective of the latest Json Schema.

• number
• integer
• string
• boolean

Number

Number.addDescription("I am a OpenAPI Number!")
  .addFormat("double")
  .addDefault(1)
  .addMinimum(0.5)
  .addMaximum(2.5)
  .addExclusiveMin(1);

{
  "type": "number",
  "description": "I am a OpenAPI Number!",
  "default": 1.5,
  "minimum": 0.5,
  "maximum": 2.5,
  "exclusiveMinimum": true,
  "format": "double"
}

Integer

Integer.addDescription("I am a OpenAPI Number!")
  .addFormat("int32")
  .addDefault(1)
  .addMinimum(0.5)
  .addMaximum(2.5)
  .addExclusiveMin(1);

Defining a String

String.addDescription("I am an OpenApi String!")
  .addDefault("OAS!")
  .addMinLength(1)
  .addMaxLength(4)
  .addPattern(/something/);

Defining a Boolean

Boolean.addDescription("I am a OpenAPI boolean!")
  .addDefault(false)
  .addExample(true);

Objects

Declare properties and other metadata on OpenAPI Object with the addProperties method.

Object.addProperties({
  firstName: String,
  lastName: String,
  id: String,
});

Arrays

Arrays can be typed with other schema types, see below for an example of a string array.

Array.addItems(String)
  .addMinItems(1)
  .addMaxItems(10)
  .addDefault(["defaultVal"]);