OpenAPI endpoints are created by setting up an <openapi /> webrule.


To add a new endpoint:

Setting up an authorization callback is required to prevent a typo/parsing error from removing all security on your API. The authorization callback can be defined at the toplevel or at any path or operation level - the most specific handler will be used. If no callback is set up, all API calls will return a 403 Forbidden error.

An operation without an implementation function will still validate parameters and authorization but return a 501 Not implemented when otherwise properly invoked.

Authorization functions should have the following signature: export async function auth(req: RestRequest): Promise<RestAuthorizationResult>

Implementation functions should have the following signature: export async function impl(req: RestRequest): Promise<WebReponse>

After setting up the above rules you should be able to access the 'openapi.json' document below the specified API path. Eg if you defined your API as follows:

    <openapiservice name="myapp" spec="openapi/myapp/myapp.yml" />
    <openapi path="root:myapp/1/" service="myapp" />

You should be able to see your API on Both this file and a Swagger-UI are linked by default from the root of your API (eg


A minimal openapi.yml file:

openapi: 3.0.2
  title: My API
  version: 1.0.0

x-webhare-authorization: openapi.ts#needSecret

- url: "."
  description: API Server

          description: A dummy
      x-webhare-implementation: openapi.ts#getDummy

The accompanying openapi.ts file:

import { createJSONResponse, RestAuthorizationResult, RestRequest } from "@webhare/router";

export async function needSecret(req: RestRequest): Promise<RestAuthorizationResult> {
  return { authorized: req.webrequest.headers.get("x-key") === "secret", authorized: null };

export async function getDummy(req: RestRequest) {
  return createJSONResponse({ answer: 42 });