ResponsibleAPI

TypeScript DSL that compiles to OpenAPI 3.1 and 3.2 documents.

Rationale

• OpenAPI YAML is hard to refactor.
• Microservices should not share implementation models, but they do share contract vocabulary: Money, CurrencyCode, error shapes, pagination, and similar boundary types.
• $defs is valid OpenAPI 3.1, but it is not a reliable public model namespace for generated SDKs. Shared contract types should compile into each service document's local components.schemas with stable #/components/schemas/... refs.

Install

npm install @responsibleapi/ts

Requires Node 22.18.0+ for plain node api.ts workflows.

Usage

import { GET, object, responsibleAPI, resp, string } from "@responsibleapi/ts"

const api = responsibleAPI({
  partialDoc: {
    openapi: "3.1.0",
    info: {
      title: "Example API",
      version: "1.0.0",
    },
  },
  routes: {
    "/hello": GET({
      res: {
        200: resp({
          description: "OK",
          body: object({
            message: string(),
          }),
        }),
      },
    }),
  },
})

console.log(JSON.stringify(api, null, 2))

Object additional properties

By default, schemas created with object() omit additionalProperties, preserving legacy output. Set a document-wide policy when explicit object openness is required:

const api = responsibleAPI({
  options: {
    objectAdditionalProperties: false,
  },
  partialDoc: {
    openapi: "3.1.0",
    info: {
      title: "Example API",
      version: "1.0.0",
    },
  },
  routes: {
    // ...
  },
})

false emits additionalProperties: false for every schema created with object(). true emits additionalProperties: true. The policy applies to nested objects and objects inside arrays, unions, nullable schemas, components, requests, and responses. It does not affect dict(), whose additionalProperties remains its value schema, or any non-object schema.

YAML Output

import { YAML } from "bun"
import { GET, object, responsibleAPI, resp, string } from "@responsibleapi/ts"

const api = responsibleAPI({
  partialDoc: {
    openapi: "3.1.0",
    info: {
      title: "Example API",
      version: "1.0.0",
    },
  },
  routes: {
    "/hello": GET({
      res: {
        200: resp({
          description: "OK",
          body: object({
            message: string(),
          }),
        }),
      },
    }),
  },
})

console.log(YAML.stringify(api))

Bun YAML docs: https://bun.com/docs/runtime/yaml

Development

Use bun