OpenApi

readOperations makes the operations Http runs from the specification of an HTTP API, which is an OpenAPI 3 document read as JSON. It reads only the document: no reference is fetched, and no address in it is used, since where requests go and what credentials they carry are the host’s to say.

Each operation becomes a tool whose input has a property for each parameter, named as the parameter is, and a property body for the JSON body. An operation that cannot be made a tool, as one with a body that is not JSON, is left out with the reason, so a host can show what it lost.

Since v0.1.0

Constructors

readOperations

Reads the operations of the API that document specifies, which is JSON already read. Nothing it refers to outside itself is fetched.

Example (A source of an API, from its OpenAPI document)

import { Http, OpenApi } from "@amends-dev/toolkit"
import { Effect, Schema } from "effect"
import { FetchHttpClient, HttpClient } from "effect/http"

declare const document: Schema.Json // the API's OpenAPI document, read as JSON

const program = Effect.gen(function* () {
  const { operations, servers, skipped } = yield* OpenApi.readOperations(document)
  // An operation that cannot be a tool is in `skipped`, with why, for a person to read.
  for (const { operation, reason } of skipped) yield* Effect.logWarning(`${operation}: ${reason}`)
  // The document's first server is where its requests go, unless the host says otherwise.
  const baseUrl = servers[0] ?? "https://petstore.example.com/api"
  const client = yield* HttpClient.HttpClient
  const petstore = yield* Http.make({ name: "petstore", baseUrl, client, operations })
  return yield* petstore.discover
}).pipe(Effect.provide(FetchHttpClient.layer))

Signature

declare const readOperations: (document: Json) => Effect.Effect<Imported, InvalidSpecError>

Source

Since v0.1.0

Errors

InvalidSpecError (class)

The document is not an OpenAPI 3 document, so there is nothing to read. An operation that cannot be a tool does not fail the read: it is in skipped.

Signature

declare class InvalidSpecError

Source

Since v0.1.0

Models

Imported (interface)

What readOperations reads of a document: the operations that are tools, the addresses of the servers it names, and the operations it left out.

Signature

export interface Imported {
  /** The operations that are tools, whose names are distinct. */
  readonly operations: ReadonlyArray<Http.Operation>

  /** The addresses the document gives for the API, which the host may offer as its base URL. */
  readonly servers: ReadonlyArray<string>

  /** The operations that are not tools, each with why. */
  readonly skipped: ReadonlyArray<Skipped>
}

Source

Since v0.1.0

Skipped (interface)

An operation that was left out of the tools, and why.

Signature

export interface Skipped {
  /** The operation as the document has it, such as `POST /pets`. */
  readonly operation: string

  /** Why the operation cannot be a tool, such as a body that is not JSON, for a person to read. */
  readonly reason: string
}

Source

Since v0.1.0