@brokkr/open-api-endpoint

The endpoint decorates server configs with an additional set of routes that generate open-api spec and a ui for it.

import http from 'http'

import { createServer, _ } from '@brokkr/rest-api-server'
import { segmentField as $, numberField, stringField } from '@brokkr/validator/fields'
import { withOpenApi } from '@brokkr/open-api-endpoint'
import { expectType } from '@brokkr/test-utils/expectType'

const itemSpec = {
  title: stringField(),
  description: stringField(),
}

const server = createServer(withOpenApi({
  routes: [
    _.POST($._('/items'))
      .body(itemSpec)
      ._resp_
      .body(numberField())
      .headers({
        title: stringField(),
      }).handler(async () => ({
        body: 42,
        headers: {
          title: 'Foo',
        },
      })),
    _.GET($._('/items'))._resp_.body(
      [itemSpec],
    ).handler(
      async () => ({
        body: [
          {
            title: 'Item N',
            description: 'Description',
          },
        ],
      }),
    )
  ]
}))

expectType<http.Server & { serve: () => http.Server }, typeof server>(true)

Once served via a regular call:

server.serve()

OpenApi ui will be available at http://localhost:8000/open-api-ui without any additional effort.