.. index:: single: open_api_provider_protocol .. _open_api_provider_protocol/0: .. rst-class:: right **protocol** ``open_api_provider_protocol`` ============================== Protocol for Logtalk objects that provide metadata used to derive OpenAPI 3.1.0 documents. | **Availability:** | ``logtalk_load(open_api(loader))`` | **Author:** Paulo Moura | **Version:** 1:0:0 | **Date:** 2026-06-08 | **Compilation flags:** | ``static`` | **Dependencies:** | (none) | **Remarks:** | (none) | **Inherited public predicates:** | (none) .. contents:: :local: :backlinks: top Public predicates ----------------- .. index:: api_info/1 .. _open_api_provider_protocol/0::api_info/1: ``api_info/1`` ^^^^^^^^^^^^^^ Returns the API metadata descriptor. The descriptor must be the compound term ``info(Title, Version, Summary, Properties)`` where ``Title``, ``Version``, and ``Summary`` are atoms and ``Properties`` is a list of optional metadata terms. Currently recognized properties: ``description(Description)`` where ``Description`` is an atom. | **Compilation flags:** | ``static`` | **Template:** | ``api_info(Info)`` | **Mode and number of proofs:** | ``api_info(-compound)`` - ``one`` ------------ .. index:: servers/1 .. _open_api_provider_protocol/0::servers/1: ``servers/1`` ^^^^^^^^^^^^^ Returns a list of server descriptors available for this API. Each descriptor must be a compound term ``server(URL, Description)`` where ``URL`` is a valid OpenAPI Server Object URL atom, allowing absolute URLs, relative references, and templated variables, and ``Description`` is a human-readable atom. | **Compilation flags:** | ``static`` | **Template:** | ``servers(Servers)`` | **Mode and number of proofs:** | ``servers(-list(compound))`` - ``one`` ------------ .. index:: security/1 .. _open_api_provider_protocol/0::security/1: ``security/1`` ^^^^^^^^^^^^^^ Returns the top-level OpenAPI security requirement alternatives for this API. The returned list uses the same representation as operation ``security(Requirements)`` properties: each element is a requirement alternative represented as a list of ``Scheme-Scopes`` pairs and ``[]`` denotes an empty security requirement object. Scheme names must be declared by ``security_scheme/2``. | **Compilation flags:** | ``static`` | **Template:** | ``security(Security)`` | **Mode and number of proofs:** | ``security(-list(compound))`` - ``zero_or_one`` ------------ .. index:: operations/1 .. _open_api_provider_protocol/0::operations/1: ``operations/1`` ^^^^^^^^^^^^^^^^ Returns a list of operation descriptors exposed by this API. Each descriptor must be a compound term ``operation(Id, Method, Path, Summary, Parameters, RequestBody, Responses, Properties)`` where ``Id`` is an atom and unique across the returned descriptors, ``Method`` is a lowercase HTTP method atom, ``Path`` is a path-template atom, ``Summary`` is an atom, ``Parameters`` is a list of ``parameter(Name, In, Description, Required, Schema)`` terms, ``RequestBody`` is either ``none`` or ``request_body(Description, Required, MediaTypes)``, ``Responses`` is a list of ``response(Status, Description, MediaTypes)`` terms, and ``Properties`` is a list of optional operation property terms. ``Status`` may be an integer HTTP status code, ``default``, or a wildcard range atom such as ``'2XX'``. Path parameters must use ``In = path``, match a template expression in ``Path``, and use ``Required = true``. Currently recognized property terms are ``description(Description)``, ``tags(Tags)``, ``deprecated(Boolean)``, and ``security(Requirements)`` where ``Requirements`` is a list whose elements are requirement alternatives represented as lists of ``Scheme-Scopes`` pairs; the empty list element ``[]`` denotes an empty security requirement object, scheme names must be declared by ``security_scheme/2``, and referenced OAuth flow scopes must be declared by the corresponding security scheme when locally available. | **Compilation flags:** | ``static`` | **Template:** | ``operations(Operations)`` | **Mode and number of proofs:** | ``operations(-list(compound))`` - ``one`` ------------ .. index:: schema/2 .. _open_api_provider_protocol/0::schema/2: ``schema/2`` ^^^^^^^^^^^^ Maps reusable schema names to JSON Schema terms. ``Name`` must be an atom and ``Schema`` must be a JSON Schema curly term compatible with the ``json_schema`` library. This predicate is intended both for lookup by name and for enumeration of all reusable schemas referenced from ``schema_ref(Name)`` terms. | **Compilation flags:** | ``static`` | **Template:** | ``schema(Name,Schema)`` | **Mode and number of proofs:** | ``schema(?atom,?compound)`` - ``zero_or_more`` ------------ .. index:: security_scheme/2 .. _open_api_provider_protocol/0::security_scheme/2: ``security_scheme/2`` ^^^^^^^^^^^^^^^^^^^^^ Maps reusable security scheme names to security descriptor terms. ``Name`` must be an atom matching scheme names referenced from operation ``security(Requirements)`` properties and ``Scheme`` must use one of the supported descriptor shapes: ``api_key/2-3``, ``http/1-2``, ``mutual_tls/0-1``, ``oauth2/1-2``, or ``openid_connect/1-2``. OAuth flow descriptors are expressed using ``implicit/2-3``, ``password/2-3``, ``client_credentials/2-3``, and ``authorization_code/3-4`` with ``scope/2`` terms. ``openid_connect/2`` also accepts a provider-only ``flows(Flows)`` option for local scope declarations used during security-reference validation; those local flow declarations are not emitted into the derived OpenAPI document. Provider-side validation checks required fields, valid ``apiKey`` locations, and URL-valued fields in OAuth or OpenID Connect descriptors. | **Compilation flags:** | ``static`` | **Template:** | ``security_scheme(Name,Scheme)`` | **Mode and number of proofs:** | ``security_scheme(?atom,?compound)`` - ``zero_or_more`` ------------ Protected predicates -------------------- (none) Private predicates ------------------ (none) Operators --------- (none)