GitHub

API reference for openapi.

The OpenAPI 3.1 document of an HttpApi (Effect's OpenApi).

from_api(api) describes every endpoint not excluded: its parameters, request body and responses, with the schemas' JSON Schemas under components.schemas. The annotations below (on the API, a group or an endpoint) fill in the document's text::

api = HttpApi.make("api").annotate(openapi.Title, "Users API")

Types

TypeDefinitionDescription
Jsontype Json = dict[str, Any]

Classes

Functions

annotations

annotations(**options) -> Context[Never]

The annotations of options (for annotate_merge).

ParameterTypeDescription
optionsUnpack[AnnotationOptions] = {}

Returns Context[Never]

def annotations(**options: Unpack[AnnotationOptions]) -> Context[Never]:
    """The annotations of ``options`` (for ``annotate_merge``)."""
    result: Context[Any] = Context.empty()
    for key, value in options.items():
        result = result.add(_ANNOTATION_TAGS[key], value)
    return result

from_api

from_api(api, **options) -> Json

The OpenAPI document of api (a fresh copy on each call). It is made once per API and option functions.

ParameterTypeDescription
apiAnyApi
optionsUnpack[FromApiOptions] = {}

Returns Json

def from_api(api: AnyApi, **options: Unpack[FromApiOptions]) -> Json:
    """The OpenAPI document of ``api`` (a fresh copy on each call). It is made once
    per API and option functions."""
    include, policy = options.get("include_annotation_key"), options.get("reference_policy")
    try:
        by_policy = _cache.setdefault(
            _NO_OPTION if include is None else include, WeakKeyDictionary()
        )
        specs = by_policy.setdefault(_NO_OPTION if policy is None else policy, WeakKeyDictionary())
    except TypeError:  # an option function that cannot be weakly referenced: not cached
        return _make(api, include, policy)
    spec = specs.get(api)
    if spec is None:
        spec = specs[api] = _make(api, include, policy)
    return copy.deepcopy(spec)