1/*  Part of SWI-Prolog
    2
    3    Author:        Jan Wielemaker
    4    E-mail:        J.Wielemaker@vu.nl
    5    WWW:           http://www.swi-prolog.org
    6    Copyright (c)  2018-2024, VU University Amsterdam
    7                              CWI, Amsterdam
    8                              SWI-Prolog Solutions b.v.
    9    All rights reserved.
   10
   11    Redistribution and use in source and binary forms, with or without
   12    modification, are permitted provided that the following conditions
   13    are met:
   14
   15    1. Redistributions of source code must retain the above copyright
   16       notice, this list of conditions and the following disclaimer.
   17
   18    2. Redistributions in binary form must reproduce the above copyright
   19       notice, this list of conditions and the following disclaimer in
   20       the documentation and/or other materials provided with the
   21       distribution.
   22
   23    THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
   24    "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
   25    LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS
   26    FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE
   27    COPYRIGHT OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT,
   28    INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING,
   29    BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
   30    LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
   31    CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
   32    LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN
   33    ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
   34    POSSIBILITY OF SUCH DAMAGE.
   35*/
   36
   37:- module(openapi,
   38          [ openapi_dispatch/1,                 % :Request
   39            openapi_server/2,                   % +File, +Options
   40            openapi_client/2,                   % +File, +Options
   41
   42            openapi_doc/3,                      % +File, +Mode, +Options
   43            openapi_arg/4                       % :PredName, ?Index, ?Name, ?Type
   44          ]).   45:- use_module(library(apply)).   46:- use_module(library(apply_macros), []).   47:- use_module(library(debug)).   48:- use_module(library(option)).   49:- use_module(library(error)).   50:- use_module(library(base64)).   51:- use_module(library(sgml)).   52:- use_module(library(lists)).   53:- use_module(library(pairs)).   54:- use_module(library(yaml)).   55:- use_module(library(uri)).   56:- use_module(library(dcg/basics)).   57:- use_module(library(http/json)).   58:- use_module(library(http/http_json)).   59:- use_module(library(http/http_parameters)).   60:- use_module(library(http/http_header)).   61:- use_module(library(listing), [portray_clause/2, portray_clause/1]).   62:- use_module(library(pprint), [print_term/2]).   63:- use_module(library(http/http_open)).   64:- use_module(library(pcre), [re_match/3]).   65:- use_module(library(dcg/high_order), [sequence/5]).   66
   67                                                % generated code.

   77:- meta_predicate
   78    openapi_dispatch(:),
   79    openapi_arg(:, ?, ?, ?).

 openapi_server(+File, +Options)

Instantiate a REST server given the OpenAPI specification in File. Normally, use `swipl-openapi --server=server.pl spec.yaml` to create a file that uses this directive and generates documentation for the server operations as well as a skeleton predicate.

   88openapi_server(File, Options) :-
   89    throw(error(context_error(nodirective, openapi_server(File, Options)), _)).
   90
   91expand_openapi_server(File, Options,
   92                      [ (:- discontiguous((openapi_handler/11,
   93                                           openapi_doc/2))),
   94                        (:- multifile((openapi_error_hook/3)))
   95                      | Clauses
   96                      ]) :-
   97    read_openapi_spec(File, Spec, Options, Options1),
   98    phrase(server_clauses(Spec, Options1), Clauses).

 openapi_client(+File, +Options)

Instantiate a REST client given the OpenAPI specification in File. Normally use `swipl-openapi --client=client.pl spec.yaml` to create a file that uses this directive and contains documentation for the generated predicates.

  107openapi_client(File, Options) :-
  108    throw(error(context_error(nodirective,
  109                              openapi_client(File, Options)), _)).

 expand_openapi_client(+File, +Options, -Clauses)

Generate clauses for the client. Currently also generates the server specification as this allows us to use the same code for generating the documentation.

  117expand_openapi_client(File, Options, AllClauses) :-
  118    AllClauses = [ (:- discontiguous(openapi_type/1))
  119                 | Clauses
  120                 ],
  121    read_openapi_spec(File, Spec, Options, Options1),
  122    phrase(client_clauses(Spec, Options1), Clauses).

 read_openapi_spec(+File, -Spec, +Options0, -Options) is det

  126read_openapi_spec(File, Spec, Options0, [yaml(Spec)|Options]) :-
  127    (   prolog_load_context(directory, Dir)
  128    ->  true
  129    ;   Dir = '.'
  130    ),
  131    absolute_file_name(File, Path,
  132                       [ relative_to(Dir),
  133                         extensions(['',json,yaml]),
  134                         access(read)
  135                       ]),
  136    uri_file_name(BaseURI, Path),
  137    openapi_read(Path, Spec),
  138    merge_options(Options0, [base_uri(BaseURI)], Options).

 openapi_read(+File, -Term) is det

Read an OpenAPI specification file.

  144openapi_read(File, Term) :-
  145    file_name_extension(_, yaml, File),
  146    !,
  147    setup_call_cleanup(
  148        open(File, read, In, [encoding(utf8)]),
  149        yaml_read(In, Term),
  150        close(In)).
  151openapi_read(File, Term) :-
  152    setup_call_cleanup(
  153        open(File, read, In, [encoding(utf8)]),
  154        json_read_dict(In, Term),
  155        close(In)).
  156
  157		 /*******************************
  158		 *       SERVER COMPILER	*
  159		 *******************************/

 server_clauses(+JSONTerm, +Options)//

Grammar to generate clauses that control openapi/1. Options processed:

base_uri(+URI)

Base URI for resolving types.

type_check_response(+Boolean)

Check the response JSON against the schema (default true)

format_response(+Boolean)

If true (default false), generate JSON with a nice layout.

  174server_clauses(JSONTerm, Options) -->
  175    { dict_pairs(JSONTerm.paths, _, Paths)
  176    },
  177    root_clause(JSONTerm.servers, Options),
  178    server_config_clauses(Options),
  179    server_path_clauses(Paths, Options),
  180    json_schema_clauses(JSONTerm, Options).
  181
  182root_clause(_, Options) -->
  183    { option(server_url(ServerURL), Options),
  184      !,
  185      uri_components(ServerURL, Components),
  186      uri_data(path, Components, Root)
  187    },
  188    !,
  189    [ openapi_root(Root) ].
  190root_clause([Server|_], _Options) -->
  191    { uri_components(Server.url, Components),
  192      uri_data(path, Components, Root)
  193    },
  194    [ openapi_root(Root) ].
  195
  196server_config_clauses(Options) -->
  197    { findall(Clause, server_config(Clause, Options), Clauses) },
  198    string(Clauses).
  199
  200server_config(openapi_server_config(type_check_response(Mode)), Options) :-
  201    option(type_check_response(Mode), Options, true).
  202server_config(openapi_server_config(reply_json_options(Opts)), Options) :-
  203    (   option(format_response(false), Options, false)
  204    ->  Opts = [width(0)]
  205    ;   Opts = []
  206    ).
  207
  208server_path_clauses([], _) --> [].
  209server_path_clauses([H|T], Options) -->
  210    (   server_path_clause(H, Options)
  211    ->  []
  212    ;   { error(openapi(path_failed, H), Options),
  213          start_debugger
  214        }
  215    ),
  216    server_path_clauses(T, Options).
  217
  218server_path_clause(Path-Spec, Options) -->
  219    { dict_pairs(Spec, _, Methods0),
  220      (   selectchk(parameters-Parms0, Methods0, Methods)
  221      ->  deref(Parms0, Parms, Options),
  222          Options1 = [parameters(Parms)|Options]
  223      ;   Methods = Methods0,
  224          Options1 = Options
  225      )
  226    },
  227    path_handlers(Methods, Path, Options1).
  228
  229path_handlers([], _Path, _) --> [].
  230path_handlers([Method-Spec|T], Path, Options) -->
  231    { path_handler(Path, Method, Spec, Fact, Options),
  232      path_docs(Method, Path, Spec, Docs, Options)
  233    },
  234    [Fact, Docs],
  235    path_handlers(T, Path, Options).

 path_handler(+Path, +Method, +Spec, -Handler, +Options) is det

Gather information about Method for Path from the YAML term Spec that describes this pair.

  242path_handler(Path, Method, Spec,
  243             openapi_handler(Method, PathList, SegmentMatches,
  244                             Request, HdrParams, AsOption, OptionParam,
  245                             Content, Responses, Security, Handler),
  246             Options) :-
  247    path_vars(Path, PathList, PathBindings),
  248    (   spec_parameters(Spec, ParamSpecs, Options)
  249    ->  server_parameters(ParamSpecs, PathBindings, SegmentMatches,
  250                          Request, AsOption, TypeAndArgs0, HdrParams,
  251                          [ path(Path),
  252                            method(Method)
  253                          | Options
  254                          ]),
  255        (   AsOption == []
  256        ->  OptionParams = []
  257        ;   OptionParams = [OptionParam]
  258        )
  259    ;   PathBindings == []
  260    ->  SegmentMatches = [],
  261        TypeAndArgs0 = [],
  262        HdrParams = [],
  263        Request = [],
  264        AsOption = [],
  265        OptionParams = []
  266    ;   error(openapi(not_covered_path_vars(Method, Path, PathBindings)),
  267              Options),
  268        fail
  269    ),
  270    content_parameter(Method, Spec, Content, TypeAndArgs0, TypeAndArgs, Options),
  271    maplist(arg(1), TypeAndArgs, Args),
  272    append(Args, [Result|OptionParams], AllArgs),
  273    dict_pairs(Spec.responses, _, ResPairs),
  274    maplist(response(Result, Options), ResPairs, Responses),
  275    spec_security(Spec, Security, Options),
  276    handler_predicate(Method, Path, Spec, PredName, Options),
  277    Handler =.. [PredName|AllArgs].
  278
  279spec_parameters(Spec, Parameters, Options) :-
  280    option(parameters(Common), Options, []),
  281    (   Me0 = Spec.get(parameters)
  282    ->  deref(Me0, Me, Options)
  283    ;   Me = []
  284    ),
  285    append(Common, Me, Parameters),
  286    Parameters \== [].

 server_parameters(+ParamSpecs, +PathBindings, -SegmentMatches, -RequestParams, -RequestOptions, -HandlerArgs, -HeaderOptions, +Options) is det

Arguments:

HandlerArgs

- is a list of a(Var,Name,Type) for the positional input arguments of the server handler predicates.

  295server_parameters([], _, [], [], [], [], [], _).
  296server_parameters([H|T], PathB, Segs, Request, AsOption, Args, HdrOpts, Options) :-
  297    _{name:NameS, in:"query"} :< H,
  298    !,
  299    phrase(http_param_options(H, Options), Opts),
  300    atom_string(Name, NameS),
  301    R0 =.. [Name,P0,Opts],
  302    (   Opts = [optional(true)|_],
  303        \+ option(optional(unbound), Options)
  304    ->  AsOption = [R0|AsOpts],
  305        server_parameters(T, PathB, Segs, Request, AsOpts, Args, HdrOpts, Options)
  306    ;   Request = [R0|Req],
  307        param_type(H, Type, Options),
  308        Args  = [a(P0,Name,Type)|MoreArgs],
  309        server_parameters(T, PathB, Segs, Req, AsOption, MoreArgs, HdrOpts, Options)
  310    ).
  311server_parameters([H|T], PathB, [segment(Type, Seg, A0, Name, Descr)|Segs],
  312                  Req, AsOption, [a(A0,Name,Type)|Args], HdrOpts, Options) :-
  313    _{name:NameS, in:"path"} :< H,
  314    !,
  315    atom_string(Name, NameS),
  316    (   memberchk(Name=Seg, PathB)
  317    ->  param_type(H, Type, Options),
  318        param_description(H, Descr)
  319    ;   option(path(Path), Options),
  320        option(method(Method), Options),
  321        error(openapi(missing_path_parameter(Method, Name, Path)), Options),
  322        fail
  323    ),
  324    server_parameters(T, PathB, Segs, Req, AsOption, Args, HdrOpts, Options).
  325server_parameters([H|T], PathB, Segs, Req, AsOption, Args, [R0|HdrOpts], Options) :-
  326    _{name:NameS, in:"header"} :< H,
  327    !,
  328    phrase(http_param_options(H, Options), Opts),
  329    atom_string(Name, NameS),
  330    R0 =.. [Name,A0,Opts],
  331    (   Opts = [optional(true)|_],
  332        \+ option(optional(unbound), Options)
  333    ->  AsOption = [R0|AsOpts],
  334        server_parameters(T, PathB, Segs, Req, AsOpts, Args, HdrOpts, Options)
  335    ;   param_type(H, Type, Options),
  336        Args  = [a(A0,Name,Type)|MoreArgs],
  337        server_parameters(T, PathB, Segs, Req, AsOption, MoreArgs, HdrOpts, Options)
  338    ).
  339server_parameters([H|T], PathB, Segs, Request, AsOption, Args, HdrOpts, Options) :-
  340    deref(H, Param, Options),
  341    !,
  342    server_parameters([Param|T], PathB, Segs, Request, AsOption, Args, HdrOpts, Options).
  343server_parameters([H|_], _PathB, _Segments, _Req, _AsOption, _, _HdrOpts, Options) :-
  344    error(openapi(parameter_failed(H)), Options),
  345    fail.
  346
  347http_param_options(Spec, Options) -->
  348    hp_optional(Spec),
  349    hp_type(Spec, Options),
  350    hp_description(Spec).
  351
  352hp_optional(Spec) -->
  353    { param_optional(Spec, optional) },
  354    !,
  355    [optional(true)].
  356hp_optional(_) --> [].
  357
  358hp_type(Spec, Options) -->
  359    hp_schema(Spec.get(schema), Options),
  360    !.
  361hp_type(_, _) --> [].
  362
  363hp_schema(Spec, Options) -->
  364    { json_type(Spec, Type, Options),
  365      json_param_type(Type, ParmType)
  366    },
  367    !,
  368    [ ParmType ].
  369hp_schema(_Spec, _Options) -->
  370    { start_debugger_fail }.
  371
  372json_param_type(array(Type, _), list(openapi(Type))) :- !.
  373json_param_type(Type, openapi(Type)).
  374
  375hp_description(Spec) -->
  376    { Descr = Spec.get(description) },
  377    !,
  378    [ description(Descr) ].
  379hp_description(_) --> [].
  380
  381deref(Spec, Yaml, Options) :-
  382    is_dict(Spec),
  383    _{'$ref':URLS} :< Spec,
  384    sub_atom(URLS, 0, _, _, './'),
  385    !,
  386    option(base_uri(Base), Options),
  387    uri_normalized(URLS, Base, URL),
  388    url_yaml(URL, Yaml).
  389deref(Spec, Yaml, Options) :-
  390    is_dict(Spec),
  391    _{'$ref':Ref} :< Spec,
  392    atomic_list_concat(Segments, /, Ref),
  393    !,
  394    option(yaml(Doc), Options),
  395    yaml_subdoc(Segments, Doc, Yaml).
  396deref(Yaml, Yaml, _).
  397
  398yaml_subdoc([], Doc, Doc).
  399yaml_subdoc([H|T], Doc, Sub) :-
  400    (   (H == '' ; H == '#')
  401    ->  Sub0 = Doc
  402    ;   Sub0 = Doc.H
  403    ),
  404    yaml_subdoc(T, Sub0, Sub).

 path_docs(+Method, +Path, +Spec, -Docs) is det

Generate documentation clauses for an operationId

  410path_docs(Method, Path, Spec,
  411          openapi_doc(OperationID, [path(Path)|Docs]),
  412          Options) :-
  413    handler_predicate(Method, Path, Spec, OperationID, [warn(false)|Options]),
  414    phrase(path_doc(Spec), Docs).

 path_doc(+Spec)//

Generate a list of documentation properties for Path

  420path_doc(Spec) -->
  421    path_doc(summary, Spec),
  422    path_doc(description, Spec),
  423    path_doc(tags, Spec).
  424
  425path_doc(Key, Spec) -->
  426    { Value = Spec.get(Key),
  427      !,
  428      Attr =.. [Key,Value]
  429    },
  430    [Attr].
  431path_doc(_, _) --> [].

 path_vars(+PathSpec, -Segments, -Bindings) is det

Convert a path specification holding {Name} into a list of Segments, where each Segment is an atom or a variable. Bindings is a list of Name=Var, e.g.

?- path_vars('/aap/{noot}/mies', Segs, B).
Segs = ['/aap/', _A, '/mies'],
B = [noot=_A].

  444path_vars(PathSpec, Segments, Bindings) :-
  445    string_codes(PathSpec, Codes),
  446    phrase(path_vars(Segments, Bindings), Codes).
  447
  448path_vars([Segment,Var|Segments], [VarName=Var|Bindings]) -->
  449    string(SegCodes), "{", string(VarCodes), "}",
  450    !,
  451    { atom_codes(Segment, SegCodes),
  452      atom_codes(VarName, VarCodes)
  453    },
  454    path_vars(Segments, Bindings).
  455path_vars(Segments, []) -->
  456    remainder(Codes),
  457    {   Codes == []
  458    ->  Segments = []
  459    ;   atom_codes(Segment, Codes),
  460        Segments = [Segment]
  461    }.

 match_path_list(+PathList, +Path) is semidet

Where PathList is a list of atoms and variables and Path is an atom. Bind the variables such that the concatenation of PathList results in Path. Each variable is bound to a string.

  469match_path_list([], "").
  470match_path_list([Path], Path) :-
  471    !.
  472match_path_list([Atom], String) :-
  473    !,
  474    atom_string(Atom, String).
  475match_path_list([H|T], Path) :-
  476    nonvar(H),
  477    !,
  478    string_concat(H, Rest, Path),
  479    match_path_list(T, Rest).
  480match_path_list([V,H|T], Path) :-
  481    assertion(nonvar(H)),
  482    sub_string(Path, B, _, A, H),
  483    sub_string(Path, 0, B, _, V),
  484    sub_string(Path, _, A, 0, Rest),
  485    match_path_list(T, Rest),
  486    !.

 content_parameter(+Method, +Spec, -Content, +ArgAndTypes0, -ArgAndTypes, +Options) is det

If there is a request body, add it to the parameter list and return a specification for openapi_dispatch/1 in Content.

  494content_parameter(Method, Spec, content(MediaType, Schema, Var, Descr),
  495                  Args, AllArgs, Options) :-
  496    has_content(Method),
  497    !,
  498    request_content_type(Spec, MediaType, Schema, Options),
  499    content_description(Spec, Descr),
  500    append(Args, [a(Var,'RequestBody',Schema)], AllArgs).
  501content_parameter(_, _, -, Args, Args, _).
  502
  503has_content(post).
  504has_content(put).
  505
  506content_description(JSON, Descr) :-
  507    Descr = JSON.get(requestBody).get(description),
  508    !.
  509content_description(_JSON, "").
  510
  511request_content_type(Spec, MediaType, Schema, Options) :-
  512    (   Body = Spec.get(requestBody)
  513    ->  true
  514    ;   Body = _{}
  515    ),
  516    !,
  517    content_type(Body, MediaType, Schema, Options).

 response(+ResultVar, +Options, +ResponsePair, -Response) is det

Describe the valid responses. Response is a term

response(Code, As, MediaType, Type, Result, Descr)

Where

• Code is the numeric HTTP status code or a variable for default
• As describes how to handle the code. Currently one of data or error
• MediaType is the expected response type
• Type is the (JSON) schema describing a JSON result
• Result is the result variable
• Descr is the description of the response body.

  534response(Result, Options, CodeA-Spec,
  535         response(Code, As, MediaType, Type, Result, Descr)) :-
  536    response_code(CodeA, Code, As),
  537    response_description(Spec, Descr),
  538    content_type(Spec, MediaType, Type, Options).
  539
  540response_code(default, _, error) :- !.
  541response_code(A, N, data) :-
  542    to_number(A, N).
  543
  544response_description(Spec, Descr) :-
  545    Descr = Spec.get(description),
  546    !.
  547response_description(_, "") .

 content_type(+Sec, -BodyType, -Schema, +Options) is det

Find the ContentType for the request body and, if applicable, its schema.

  554content_type(_Spec, media(application/json, []), Type, Options) :-
  555    option(type_check_request(false), Options),
  556    !,
  557    Type = (-).
  558content_type(Spec, media(application/json, []), Type, Options) :-
  559    Content = Spec.get(content),
  560    Media = Content.get('application/json'),
  561    !,
  562    (   Schema = Media.get(schema)
  563    ->  json_type(Schema, Type, Options)
  564    ;   Type = (-)
  565    ).
  566content_type(_Spec, media(Type, []), -, Options) :-
  567    option(default_request_body_type(Type0), Options),
  568    !,
  569    to_content_type(Type0, Type).
  570content_type(_Spec, media(application/json, []), -, _).
  571
  572to_content_type(Type0, Main/Sub) :-
  573    atomic(Type0),
  574    atomic_list_concat([Main,Sub], /, Type0),
  575    !.
  576to_content_type(Type, Type) :-
  577    Type = Main/Sub,
  578    must_be(atom, Main),
  579    must_be(atom, Sub).
  580to_content_type(Type, _) :-
  581    type_error(content_type, Type).
  582
  583
  584		 /*******************************
  585		 *       CLIENT COMPILER	*
  586		 *******************************/

 client_clauses(+JSONTerm, +Options)//

Generate clauses for the client. The generated clauses are:

• openapi_server(URL) One or more clauses describing the location of the server as defined in the OpenAPI file. If the option server_url(ServerURL) is provided, this replaces the locations found in the OpenAPI file.
• Clauses that call the REST methods. The name is the operationId described in the Swagger file. The arguments are defined by the parameters and response from the OpenAPI specification.
• openapi:json_schema(URL, Type) Clauses that define the JSON schema types.

  604client_clauses(JSONTerm, Options) -->
  605    { dict_pairs(JSONTerm.paths, _, Paths)
  606    },
  607    server_url_clauses(JSONTerm.servers, Options),
  608    client_path_clauses(Paths, Options),
  609    json_schema_clauses(JSONTerm, Options).
  610
  611server_url_clauses(_Servers, Options) -->
  612    { option(server_url(ServerURL), Options)
  613    },
  614    !,
  615    [ openapi_server(ServerURL) ].
  616server_url_clauses(Servers, _Options) -->
  617    server_url_clauses(Servers).
  618
  619server_url_clauses([]) --> [].
  620server_url_clauses([H|T]) --> server_url_clauses(H), server_url_clauses(T).
  621
  622server_url_clauses(Server) -->
  623    [ openapi_server(Server.get(url)) ].
  624
  625client_path_clauses([], _) --> [].
  626client_path_clauses([H|T], Options) -->
  627    (   client_path_clause(H, Options)
  628    ->  []
  629    ;   { error(openapi(path_failed, H), Options) }
  630    ),
  631    client_path_clauses(T, Options).
  632
  633client_path_clause(Path-Spec, Options) -->
  634    { dict_pairs(Spec, _, Methods0),
  635      (   selectchk(parameters-Parms, Methods0, Methods)
  636      ->  Options1 = [parameters(Parms)|Options]
  637      ;   Methods = Methods0,
  638          Options1 = Options
  639      )
  640    },
  641    client_handlers(Methods, Path, Options1).
  642
  643client_handlers([], _, _) --> [].
  644client_handlers([H|T], Path, Options) -->
  645    { client_handler(H, Path, Clause, TypeClause, Options) },
  646    [Clause, TypeClause],
  647    client_handlers(T, Path, Options).
  648
  649:- det(client_handler/5).  650client_handler(Method-Spec, PathSpec, (Head :- Body), openapi_type(TypeHead), Options) :-
  651    path_vars(PathSpec, PathList, PathBindings),
  652    handler_predicate(Method, PathSpec, Spec, PredName, Options),
  653    (   spec_parameters(Spec, ParamSpecs, Options)
  654    ->  client_parameters(ParamSpecs, PathBindings,
  655                          ArgAndTypes, HdrParams, Query, Optional,
  656                          CheckParams,
  657                          [ path(PathSpec),
  658                            method(Method)
  659                          | Options
  660                          ]),
  661        (   Optional == []
  662        ->  ClientOptionArgs = []
  663        ;   ClientOptionArgs = [ClientOptions]
  664        )
  665    ;   PathBindings == []
  666    ->  ArgAndTypes = [],
  667        Query = [],
  668        CheckParams = true,
  669        Optional = [],
  670        ClientOptionArgs = [],
  671        HdrParams = []
  672    ;   error(openapi(not_covered_path_vars(Method, PathSpec, PathBindings)),
  673              Options),
  674        fail
  675    ),
  676    content_parameter(Method, Spec, Content, ArgAndTypes, ArgAndTypes1, Options),
  677    maplist(arg(1), ArgAndTypes1, Args),
  678    maplist(client_arg, ArgAndTypes1, ClientArgs),
  679    TypeHead =.. [PredName|ClientArgs],
  680    request_body(Method, PathSpec, Module, Content, ContentGoal, RequestOptions),
  681    dict_pairs(Spec.responses, _, ResPairs),
  682    maplist(response(Result, Options), ResPairs, Responses),
  683    (   response_has_data(Responses)
  684    ->  ResultArgs = [Result]
  685    ;   ResultArgs = []
  686    ),
  687    append([ Args,
  688             ResultArgs,
  689             ClientOptionArgs
  690           ], AllArgs),
  691    spec_security(Spec, Security, Options),
  692    prolog_load_context(module, Module),
  693    (   PathBindings == []
  694    ->  Path = PathSpec,
  695        PathGoal = true
  696    ;   PathGoal = atomic_list_concat(PathList, Path)
  697    ),
  698    Head =.. [PredName|AllArgs],
  699    Body = ( CheckParams, PathGoal, ContentGoal,
  700             openapi:assemble_query(Module, Method, Path,
  701                                    HdrParams, Query, Optional, ClientOptions,
  702                                    URL, HdrOptions),
  703             context_module(CM),
  704             openapi:assemble_security(Security, CM, SecOptions),
  705             append([ SecOptions,
  706                      RequestOptions,
  707                      HdrOptions
  708                    ], OpenOptions),
  709             debug(openapi(client), '~w ~w', [Method, URL]),
  710             setup_call_cleanup(
  711                 openapi:http_open(URL, In,
  712                           [ status_code(Status),
  713                             method(Method),
  714                             header(content_type, ContentType),
  715                             request_header(accept = 'application/json')
  716                           | OpenOptions
  717                           ]),
  718                 openapi:openapi_read_reply(Status, ContentType, Responses,
  719                                            In, Result),
  720                 close(In))
  721           ).
  722
  723:- det(client_arg/2).  724client_arg(a(_, Name, Type), ArgName:Type) :-
  725    camel_case(Name, ArgName).

 handler_predicate(+Method, +Path, +Spec, -PredicateName, +Options) is det

Generate a predicate name from a specification. Prefers the operationId.

  732handler_predicate(_, _, Spec, PredicateName, _Options) :-
  733    uncamel_case(Spec.get(operationId), PredicateName),
  734    !.
  735handler_predicate(Method, Path, _Spec, PredicateName, Options) :-
  736    atomic_list_concat(Segments, /, Path),
  737    reverse(Segments, RevSegments),
  738    member(Segment, RevSegments),
  739    \+ sub_atom(Segment, _, _, _, '{'),
  740    !,
  741    file_name_extension(Name, _, Segment),
  742    atomic_list_concat([Method, '_', Name], PredicateName),
  743    (   option(warn(true), Options, true)
  744    ->  warning(openapi(no_operation_id, Method, Path, PredicateName), Options)
  745    ;   true
  746    ).

 response_has_data(+Responses) is semidet

True if the request (may) return data. This is not the case if the only responses are 204 (no content) or error codes that are mapped to exceptions.

  755response_has_data(Responses) :-
  756    maplist(arg(1), Responses, Codes),
  757    member(Code, Codes),
  758    \+ code_has_no_data(Code), !.
  759
  760code_has_no_data(Code) :-
  761    var(Code).                                  % errors
  762code_has_no_data(204).                          % No content

 client_parameters(+Spec, +PathBindings, -ArgsAndTypes, -HdrParams, -Required, -Optional, -Check:callable, +Options)

Arguments:

Args	- is a list of pairs a(Var,Name,Type) for required arguments of the client predicate.
Required	- is a list of qparam(Name,P0,Type,Opt) used for adding query parameters for required parameters to the URL
Optional	- is a list of qparam(Name,P0,Type,optional) used for adding query parameters for optional parameters to the URL
Check	- is a callable term for validating the arguments,

  776client_parameters([], _, [], [], [], [], true, _).
  777client_parameters([H|T], PathBindings, [a(A0,Name,Type)|Args], HdrParams,
  778                  [qparam(Name,A0,Type,Opt)|Qs], Optional, Check, Options) :-
  779    _{name:NameS, in:"query"} :< H,
  780    param_optional(H, Opt),
  781    \+ ( Opt == optional,
  782         \+ option(optional(unbound), Options)
  783       ),
  784    !,
  785    param_type(H, Type, Options),
  786    atom_string(Name, NameS),
  787    client_parameters(T, PathBindings, Args, HdrParams, Qs, Optional, Check, Options).
  788client_parameters([H|T], PathBindings, [a(A0,Name,Type)|Args],
  789                  [hparam(Name,A0,Type,Opt)|HdrParams],
  790                  Query, Optional, Check, Options) :-
  791    _{name:NameS, in:"header"} :< H,
  792    param_optional(H, Opt),
  793    \+ ( Opt == optional,
  794         \+ option(optional(unbound), Options)
  795       ),
  796    !,
  797    param_type(H, Type, Options),
  798    atom_string(Name, NameS),
  799    client_parameters(T, PathBindings, Args, HdrParams, Query, Optional, Check, Options).
  800client_parameters([H|T], PathBindings,
  801                  Params, HdrParams, Query, [qparam(Name,_,Type,optional)|OptT],
  802                  Check, Options) :-
  803    _{name:NameS, in:"query"} :< H,
  804    !,
  805    param_type(H, Type, Options),
  806    atom_string(Name, NameS),
  807    client_parameters(T, PathBindings, Params, HdrParams,
  808                      Query, OptT, Check, Options).
  809client_parameters([H|T], PathBindings, Args,
  810                  [hparam(Name,_,Type,optional)|HdrParams], Query, Optional,
  811                  Check, Options) :-
  812    _{name:NameS, in:"header"} :< H,
  813    !,
  814    param_type(H, Type, Options),
  815    atom_string(Name, NameS),
  816    client_parameters(T, PathBindings, Args, HdrParams,
  817                      Query, Optional, Check, Options).
  818client_parameters([H|T], PathBindings, [a(A0,Name,Type)|Args],
  819                  HdrParams, Query, Opt, Check, Options) :-
  820    _{name:NameS, in:"path"} :< H,
  821    !,
  822    atom_string(Name, NameS),
  823    param_type(H, Type, Options),
  824    (   memberchk(Name=Segment, PathBindings)
  825    ->  Check1 = openapi:segment_value(Type, Segment, A0)
  826    ;   option(path(Path), Options),
  827        option(method(Method), Options),
  828        error(openapi(missing_path_parameter(Method, Name, Path)), Options),
  829        fail
  830    ),
  831    client_parameters(T, PathBindings, Args, HdrParams,
  832                      Query, Opt, Check0, Options),
  833    mkconj(Check0, Check1, Check).
  834client_parameters([H|T], PathBindings, Args, HdrParams,
  835                  Query, Opt, Check, Options) :-
  836    deref(H, Param, Options),
  837    !,
  838    client_parameters([Param|T], PathBindings, Args, HdrParams,
  839                      Query, Opt, Check, Options).
  840
  841param_optional(Spec, Optional) :-
  842    (   Spec.get(required) == false
  843    ->  Optional = optional
  844    ;   _Default = Spec.get(schema).get(default)
  845    ->  Optional = optional
  846    ;   Optional = required
  847    ).
  848
  849param_type(Spec, Type, Options) :-
  850    json_type(Spec.get(schema), Type, Options),
  851    !.
  852param_type(_Spec, any, _Options).
  853
  854param_description(Spec, Description) :-
  855    Description = Spec.get(description),
  856    !.
  857param_description(_Spec, "").
  858
  859mkconj(true, G, G) :- !.
  860mkconj(G, true, G) :- !.
  861mkconj(G1, G2,  (G1,G2)).

 request_body(+Method, +Path, +Module, +ContentSpec, -Goal, -HTTPOPenOptions) is det

Translate the request body into options for http_open/3.

  868request_body(Method, Path, Module,
  869	     content(media(application/json,_), Schema, InVar, _Descr),
  870             openapi:assemble_content(Module, Method, Path,
  871                                      json, Schema, InVar, OutVar),
  872             [ post(json(OutVar))
  873             ]) :-
  874    !.
  875request_body(Method, Path, Module,
  876	     content(media(multipart/'form-data',_), Schema, InVar, _Descr),
  877             openapi:assemble_content(Module, Method, Path,
  878                                      form_data, Schema, InVar, OutVar),
  879             [ post(form_data(OutVar))
  880             ]) :-
  881    !.
  882request_body(_, _, _, content(MediaType, _Schema, _Var, _Descr), _, _) :-
  883    !,
  884    domain_error(openapi(content_type), MediaType).
  885request_body(_, _, _, _, true, []).
  886
  887
  888		 /*******************************
  889		 *           SECURITY		*
  890		 *******************************/

 spec_security(+MethodSpec, -Security:list, +Options) is det

Decode the required authentication for sending a request. Security is a list of admissible authentication methods and has the following possible values:

public

No authentication needed. This is (with a warning) also emitted for schemes we do not yet support.

http(Scheme, Name, Args)

For http basic and http bearer authentications. Name is the name of the security scheme from the OpenAPI document.

api_key(header(Header),Name,Args)

We need to provide an api key in an additional header named Header. Name is the name of the security scheme from the OpenAPI document.

To be done

- Currently only deals with authorization we need in dealing with the hypothesis API.

  912spec_security(Spec, Security, Options) :-
  913    maplist(security(Options), Spec.get(security), Security),
  914    Security \== [],
  915    !.
  916spec_security(_, [public], _).
  917
  918security(Options, Sec, Security) :-
  919    dict_pairs(Sec, _, [Scheme-Args]),
  920    option(yaml(Doc), Options),
  921    yaml_subdoc([components, securitySchemes,Scheme], Doc, SchemeObj),
  922    security_scheme(Scheme, SchemeObj, Args, Security, Options).
  923security(_Options, Sec, public) :-
  924    dict_pairs(Sec, _, []),
  925    !.
  926
  927security_scheme(SchemeName, Dict, Args,
  928                http(Scheme, SchemeName, Args), _Options) :-
  929    _{type: "http", scheme: SchemeS} :< Dict,
  930    !,
  931    atom_string(Scheme, SchemeS).
  932security_scheme(SchemeName, Dict, Args,
  933                api_key(header(Name), SchemeName, Args), _Options) :-
  934    _{type: "apiKey", in: "header", name: NameS} :< Dict,
  935    !,
  936    atom_string(Name, NameS).
  937security_scheme(SchemeName, Dict, _, public, Options) :-
  938    warning(openapi(unknown_security_scheme(SchemeName, Dict)), Options).
  939
  940
  941		 /*******************************
  942		 *       RUNTIME SUPPORT	*
  943		 *******************************/
  944
  945:- public
  946    assemble_query/9,
  947    assemble_content/7.

 assemble_query(+Module, +Method, +Path, +HeaderParams, +QParams, +QOptional, +QOptions, -URL, -OpenOptions) is det

Arguments:

QOptions

- is the option list of the client predicate.

  954assemble_query(Module, Method, Path, HeaderParams, QParams, QOptional, QOptions,
  955               URL, OpenOptions) :-
  956    call(Module:openapi_server(ServerBase)),
  957    convlist(client_query_param, QParams, QueryFromArgs),
  958    optional_query_params(QOptional, QOptions, QueryFromOptions),
  959    application_extra_query_parameters(Module, Method, Path, Extra),
  960    append([Extra, QueryFromArgs, QueryFromOptions], Query),
  961    (   Query == []
  962    ->  atomics_to_string([ServerBase, Path], URL)
  963    ;   phrase(array_query(Query), ArrayQuery),
  964        uri_query_components(QueryString, ArrayQuery),
  965        atomics_to_string([ServerBase, Path, "?", QueryString], URL)
  966    ),
  967    convlist(client_header_param(QOptions), HeaderParams, OpenOptions).
  968
  969assemble_content(Module, Method, Path, Format, Schema, In, Content) :-
  970    (   Schema == (-)
  971    ->  Content0 = In
  972    ;   json_check(Schema, Content0, In)
  973    ),
  974    (   current_predicate(Module:extend_content/5),
  975        Module:extend_content(Method, Path, json, Content0, Content1)
  976    ->  true
  977    ;   Content1 = Content0
  978    ),
  979    output_format(Format, Content1, Content).
  980
  981output_format(json, Content, Content).
  982output_format(form_data, Dict, Form) :-
  983    dict_pairs(Dict, _, FormPairs),
  984    maplist(form_entry, FormPairs, Form).
  985
  986form_entry(Name-Value, Name=Value).

 application_extra_query_parameters(+Module, +Method, +Path, -Extra) is det

Allow a client to specify additional query parameters that do not appear in the OpenAPI spec but apply to all methods. This is sometimes used to supply credentials.

  994application_extra_query_parameters(Module, Method, Path, Extra) :-
  995    current_predicate(Module:extra_query_parameters/3),
  996    Module:extra_query_parameters(Method, Path, Extra),
  997    !,
  998    must_be(list, Extra).
  999application_extra_query_parameters(_, _, _, []).

 array_query(Query)//

Rewrite Name=List into Name=E1, Name=E2, ... to support array(Type, Opts) for parameters passed as queries.

 1008array_query([]) --> [].
 1009array_query([Name=Value|T]) -->
 1010    (   {is_list(Value)}
 1011    ->  repeat_query(Value, Name)
 1012    ;   [Name=Value]
 1013    ),
 1014    array_query(T).
 1015
 1016repeat_query([], _) --> [].
 1017repeat_query([H|T], Name) -->
 1018    [ Name=H ],
 1019    repeat_query(T, Name).

 client_query_param(+Spec, -QueryElement) is det

Perform type validation and transformation for the client Prolog value to something suitable to pass onto uri_query_components/2.

 1026client_query_param(qparam(Name, PlValue, Type, _Required),
 1027                   Name = Value) :-
 1028    nonvar(PlValue),
 1029    !,
 1030    (   Type == any
 1031    ->  Value = PlValue
 1032    ;   json_check(Type, Value, PlValue)
 1033    ).
 1034client_query_param(qparam(_Name, _PlValue, _Type, optional), _) :-
 1035    !, fail.                                    % leave to convlist/3.
 1036client_query_param(qparam(_Name, PlValue, Type, required), _) :-
 1037    type_error(Type, PlValue).
 1038
 1039optional_query_params([], _, []).
 1040optional_query_params([qparam(Name, PlValue, Type, optional)|T0], Options, Q) :-
 1041    Term =.. [Name,PlValue],
 1042    option(Term, Options),
 1043    !,
 1044    json_check(Type, Value, PlValue),
 1045    Q = [Name=Value|QT],
 1046    optional_query_params(T0, Options, QT).
 1047optional_query_params([_|T0], Options, Q) :-
 1048    optional_query_params(T0, Options, Q).

 client_header_param(+QOptions, +HeaderParam, -Header) is semidet

 1054client_header_param(_QOptions, hparam(Name, PlValue, Type, _Required),
 1055                    request_header(Name=Value)) :-
 1056    nonvar(PlValue),
 1057    !,
 1058    (   Type == any
 1059    ->  Value = PlValue
 1060    ;   json_check(Type, Value, PlValue)
 1061    ).
 1062client_header_param(QOptions, hparam(Name, _PlValue, Type, _Required),
 1063                    request_header(Name=Value)) :-
 1064    Opt =.. [Name,PlValue],
 1065    option(Opt, QOptions),
 1066    !,
 1067    json_check(Type, Value, PlValue).
 1068client_header_param(_QOptions, hparam(Name, _PlValue, _Type, required),
 1069                    _) :-
 1070    existence_error(openapi_option, Name).

 segment_value(+Type, ?Segment, ?Prolog) is det

Transform between a Segment string and the Prolog value according to Type.

 1077segment_value(Type, Segment, Prolog) :-
 1078    nonvar(Segment),
 1079    !,
 1080    uri_encoded(segment, Value, Segment),
 1081    json_check(Type, Value, Prolog).
 1082segment_value(Type, Segment, Prolog) :-
 1083    json_check(Type, Value, Prolog),
 1084    uri_encoded(segment, Value, Segment).

 openapi_read_reply(+Code, +ContentType, +Responses, +In, -Result) is det

Handle the reply at the client side.

 1090:- public openapi_read_reply/5. 1091
 1092openapi_read_reply(Code, _ContentType, Responses, _In, Result) :-
 1093    no_content(Code),
 1094    !,
 1095    (   memberchk(response(Code, _As, _ExpectedContentType, _Type, _Result, _Comment),
 1096                  Responses)
 1097    ->  Result = true
 1098    ;   maplist(arg(1), Responses, ExCodes),
 1099        throw(error(openapi_invalid_reply(Code, ExCodes, ""), _))
 1100    ).
 1101openapi_read_reply(Code, ContentType, Responses, In, Result) :-
 1102    debug(openapi(reply), 'Got code ~p; type: ~p; response schemas: ~p',
 1103          [Code, ContentType, Responses]),
 1104    http_parse_header_value(content_type, ContentType, ParsedContentType),
 1105    (   memberchk(response(Code, As, ExpectedContentType, Type, _Result, _Comment),
 1106                  Responses)
 1107    ->  true
 1108    ;   read_reply(ParsedContentType, -, data, Code, In, Error),
 1109        maplist(arg(1), Responses, ExCodes),
 1110        throw(error(openapi_invalid_reply(Code, ExCodes, Error), _))
 1111    ),
 1112    content_matches(ExpectedContentType, ParsedContentType, ProcessType),
 1113    read_reply(ProcessType, Type, As, Code, In, Result).
 1114
 1115no_content(204).
 1116
 1117content_matches(ContentType, ContentType, ContentType) :- !.
 1118content_matches(media(Type, _), media(Type, Attrs), media(Type, Attrs)) :- !.
 1119content_matches(Expected, Got, _) :-
 1120    type_error(media(Expected), Got).
 1121
 1122read_reply(media(application/json, _), Type, As, Code, In, Result) :-
 1123    json_read_dict(In, Result0, []),
 1124    (   debugging(openapi(reply_object))
 1125    ->  print_term(Result0, [])
 1126    ;   true
 1127    ),
 1128    (   Type = (-)
 1129    ->  Result = Result0
 1130    ;   json_check(Type, Result0, Result1)
 1131    ),
 1132    reply_result(As, Code, Result1, Result).
 1133
 1134reply_result(data,  _Code, Result, Result).
 1135reply_result(error, Code, Result, _ ) :-
 1136    throw(error(rest_error(Code, Result), _)).

 assemble_security(+Security, +ClientModule, -HTTPOptions)

Assemble additional HTTP options from the security description.

 1142:- public assemble_security/3. 1143assemble_security(Security, CM, SecOptions) :-
 1144    current_predicate(CM:security_options/2),
 1145    CM:security_options(Security, SecOptions), !.
 1146assemble_security(Security, _, []) :-
 1147    memberchk(public, Security),
 1148    !.
 1149assemble_security(Security, _, _) :-
 1150    existence_error(security_data, Security).

 security_options(+Security:list, -SecOptions:list)

Multifile hook to provide additional HTTP options for realizing a specific security/authentication. The application must define this hook for dealing with authentication. The possible Security inputs are described with spec_security/3. If this hook fails and the API handler may be accessed without security access without additional options is tried. If this hook fails and authentication is required the client call raises an existence_error for security_data.

 1164		 /*******************************
 1165		 *          DISPATCHER		*
 1166		 *******************************/

 openapi_dispatch(:Request) is semidet

Generic HTTP handler to deal with OpenAPI REST requests.

To be done

-

• validate types
• handle errors
• different replies formats
• different reply codes

 1177openapi_dispatch(M:Request) :-
 1178    memberchk(path(FullPath), Request),
 1179    memberchk(method(Method), Request),
 1180    M:openapi_root(Root),
 1181    atom_concat(Root, Path, FullPath),
 1182    M:openapi_handler(Method, PathList, Segments,
 1183                      Required, HdrParams, AsOption, OptionParam, Content,
 1184                      Responses, _Security,
 1185                      Handler),
 1186    match_path_list(PathList, Path),
 1187    !,
 1188    (   catch(openapi_run(M:Request,
 1189                          Segments,
 1190                          Required, HdrParams, AsOption, OptionParam, Content,
 1191                          Responses,
 1192                          Handler),
 1193              Error,
 1194              openapi_error(M, Error, Responses))
 1195    ->  true
 1196    ;   openapi_error(M, failed, Responses)
 1197    ).
 1198
 1199openapi_run(Module:Request,
 1200            Segments,
 1201            Required, HdrParams, AsOption, OptionParam, Content,
 1202            Responses,
 1203            Handler) :-
 1204    append(Required, AsOption, RequestParams),
 1205    catch(( maplist(segment_parameter, Segments),
 1206            maplist(header_parameter(Request), HdrParams),
 1207            http_parameters([method(get)|Request], RequestParams),
 1208            request_body(Content, Request),
 1209            server_handler_options(AsOption, OptionParam)
 1210          ), IE, input_error(IE, RequestParams)),
 1211    call(Module:Handler),
 1212    catch(openapi_reply(Module, Responses), OE,
 1213          output_error(OE)).

 input_error(+Error, +RequestParams)

 output_error(+Error)

Handle errors while converting the input and output parameters. Currently maps error context from http_parameters/2 to rest(Param, query, Type) context.

 1222input_error(error(Formal, Context), RequestParams) :-
 1223    subsumes_term(context(_, http_parameter(_)), Context),
 1224    Context = context(_, http_parameter(Param)),
 1225    debug(rest(error), 'Error in ~p; request = ~p', [Param, RequestParams]),
 1226    member(ReqParam, RequestParams),
 1227    ReqParam =.. [Param, _Value, Options],
 1228    http_param_type(Options, Type),
 1229    !,
 1230    throw(error(Formal, rest(Param, request, Type))).
 1231input_error(E, _RequestParams) :- throw(E).
 1232
 1233http_param_type(Options, Type) :-
 1234    memberchk(openapi(Type), Options),
 1235    !.
 1236http_param_type(Options, array(Type, _)) :-
 1237    memberchk(list(openapi(Type)), Options),
 1238    !.
 1239
 1240output_error(E) :- throw(E).
 1241
 1242:- meta_predicate
 1243    add_error_context(0, +). 1244
 1245add_error_context(Goal, C) :-
 1246    catch(Goal, error(Formal, _), throw(error(Formal, C))).

 segment_parameter(?Segment)

Fill a segment parameter

 1252segment_parameter(segment(Type, Segment, Value, Name, _Description)) :-
 1253    add_error_context(
 1254        segment_value(Type, Segment, Value),
 1255        rest(Name, path, Type)).
 1256
 1257server_handler_options([], []).
 1258server_handler_options([H|T], Options) :-
 1259    arg(1, H, Value),
 1260    (   var(Value)
 1261    ->  server_handler_options(T, Options)
 1262    ;   functor(H, Name, _),
 1263        Opt =.. [Name,Value],
 1264        Options = [Opt|OptT],
 1265        server_handler_options(T, OptT)
 1266    ).

 header_parameter(+Request, +HdrParam)

Extract a parameter through the header. @tbd Deal with name normalization? Deal with optional and missing required values.

 1274header_parameter(Request, HdrParam) :-
 1275    HdrParam =.. [Name, Arg, _Opts],
 1276    Header =.. [Name,Arg],
 1277    (   memberchk(Header, Request)
 1278    ->  true
 1279    ;   print_message(warning, error(rest_error(missing_header(Name)), _))
 1280    ).

 request_body(+ContentSpec, +Request) is det

Read the specified request body.

 1286request_body(-, _).
 1287request_body(content(media(application/json,_), -, Body, _Descr), Request) :-
 1288    !,
 1289    add_error_context(
 1290        http_read_json_dict(Request, Body),
 1291        rest(body, request_body, json)).
 1292request_body(content(media(application/json,_), Type, Body, _Descr), Request) :-
 1293    add_error_context(
 1294        http_read_json_dict(Request, Body0),
 1295        rest(body, request_body, json)),
 1296    add_error_context(
 1297        json_check(Type, Body0, Body),
 1298        rest(body, request_body, Type)).

 openapi_reply(+Module, +Responses) is det

Formulate the HTTP request from a term. The user handler binds the response parameter to one of:

status(Code)

Reply using an HTTP header with status Code and no body.

status(Code, Data)

Use Code as HTTP status code and generate the body from Data. Currently this only supports responses of the type application/json and Data must be suitable for json_write_dict/3.

Arguments:

Responses

- is a list response(Code, MediaType, Type, Reply, Description), where Reply is the variable that is bound by the user supplied handler.

 1317:- det(openapi_reply/2). 1318openapi_reply(Module, Responses) :-
 1319    Responses = [R0|_],
 1320    arg(5, R0, Reply),
 1321    reply_status(Reply, Code, Data),
 1322    memberchk(response(Code, _As, MediaType, Type, _, _Descr), Responses),
 1323    openapi_reply(Code, MediaType, Type, Data, Module).
 1324
 1325reply_status(Var, _, _) :-
 1326    var(Var), !,
 1327    instantiation_error(Var).
 1328reply_status(status(Code, Data), Code, Data) :- !.
 1329reply_status(status(Code), Code, '') :- !.
 1330reply_status(Data, 200, Data).

 openapi_reply(+HTTPCode, +MediaType, +Type, +Data, +Module) is det

 1334:- det(openapi_reply/5). 1335openapi_reply(Code, _, _, '', _) :-
 1336    !,
 1337    format('Status: ~d~n~n', [Code]).
 1338openapi_reply(Code, media(application/json,_), -, Data, Module) :-
 1339    !,
 1340    Module:openapi_server_config(reply_json_options(Options)),
 1341    reply_json_dict(Data, [status(Code)|Options]).
 1342openapi_reply(Code, media(application/json,_), Type, Data, Module) :-
 1343    !,
 1344    (   Module:openapi_server_config(type_check_response(true))
 1345    ->  json_check(Type, Out, Data)
 1346    ;   Out = Data
 1347    ),
 1348    Module:openapi_server_config(reply_json_options(Options)),
 1349    reply_json_dict(Out, [status(Code)|Options]).

 openapi_error(+Module, +Error, +Responses) is det

An error happened while converting the input arguments, running the implementation or converting the output arguments.

Arguments:

Module	- is the (server) module
Error	- is the exception or the atom failed if the body execution failed.
Responses	- are the declared valid responses.

 1361openapi_error(Module, Error, Responses) :-
 1362    map_error(Module, Error, Responses, Reply),
 1363    Responses = [R0|_],
 1364    arg(5, R0, Reply),
 1365    openapi_reply(Module, Responses),
 1366    !.
 1367openapi_error(_Module, Error, _Responses) :-
 1368    throw(Error).
 1369
 1370map_error(Module, Error, Responses, Reply) :-
 1371    call(Module:openapi_error_hook(Error, Responses, Reply)),
 1372    !.
 1373map_error(_Module, Error, _Responses, Reply) :-
 1374    Error = error(_, Context),
 1375    nonvar(Context),
 1376    http_error_status(Context, Error, Status),
 1377    message_to_string(Error, Message),
 1378    Reply = status(Status, _{code:Status, message:Message}).
 1379
 1380http_error_status(rest(_,_,_), _, 400).

 openapi_error_hook(+Error, +Responses, -Reply) is semidet

Hook called in the server module if an error was encountered while processing the REST request. If the error was thrown while extracting and converting the request parameters, the context of the exception (2nd argument of the error/2 term) has the following shape:

rest(Parameter, Location, Type)

Where Parameter is the parameter name or body, Location is path, query or request_body, and Type is the translated JSON schema type if the parameter. The generated error is typically a type_error, domain_error or syntax_error.

Arguments:

Responses	- contains a description of the valid response types and codes.
Reply	- is typically bound to a term status(Code, Object), where Object is a dict describing the error.

 1402		 /*******************************
 1403		 *            TYPES		*
 1404		 *******************************/

 api_type(?Type, ?Format, ?TypeID) is semidet

 1410api_type(Type, Format, TypeID) :-
 1411    api_type(_Name, Type, Format, TypeID), !.
 1412api_type(string, Format, string) :-
 1413    !,
 1414    print_message(warning, openapi(unknown_string_format, Format)).
 1415api_type(Type, Format, _TypeID) :-
 1416    print_message(error, openapi(unknown_type, Type, Format)),
 1417    fail.

 api_type(?Name, ?Type, ?Format, ?TypeID)

The formats defined by the OAS are:

 1424api_type(integer,  integer,    int32,       int32).
 1425api_type(long,     integer,    int64,       int64).
 1426api_type(long,     integer,    -,           integer).
 1427api_type(float,    number,     float,       float).
 1428api_type(double,   number,     double,      float).
 1429api_type(double,   number,     -,           float).
 1430api_type(string,   string,     -,           string).
 1431api_type(byte,     string,     byte,        base64).
 1432api_type(binary,   string,     binary,      binary).
 1433api_type(boolean,  boolean,    -,           boolean).
 1434api_type(date,     string,     date,        date).
 1435api_type(dateTime, string,     'date-time', date_time).
 1436api_type(password, string,     password,    password).
 1437api_type(string,   string,     string,      string). % Not in OAS
 1438api_type(uri,      string,     uri,         uri).    % Not in OAS
 1439api_type(uuid,     string,     uuid,        uuid).   % Not in OAS

 oas_type(+Type, ?In, ?Out) is det

Arguments:

Out	- is the Prolog view
In	- is the JSON dict view.

 1446oas_type(int32, In, Out) :-
 1447    cvt_integer(In, Out),
 1448    must_be(between(-2147483648, 2147483647), Out).
 1449oas_type(int64, In, Out) :-
 1450    cvt_integer(In, Out),
 1451    must_be(between(-9223372036854775808, 9223372036854775807), Out).
 1452oas_type(integer, In, Out) :-
 1453    cvt_integer(In, Out).
 1454oas_type(number, In, Out) :-
 1455    cvt_number(In, Out).
 1456oas_type(float, In, Out) :-
 1457    (   nonvar(In)
 1458    ->  cvt_number(In, Out0),
 1459        Out is float(Out0)
 1460    ;   cvt_number(In0, Out),
 1461        In is float(In0)
 1462    ).
 1463oas_type(string, In, Out) :-
 1464    (   var(In)
 1465    ->  to_string(Out, In)
 1466    ;   to_atom(In, Out)
 1467    ).
 1468oas_type(uri, In, Out) :-
 1469    (   var(In)
 1470    ->  to_atom(Out, In)
 1471    ;   to_atom(In, Out)
 1472    ).
 1473oas_type(uuid, In, Out) :-
 1474    (   var(In)
 1475    ->  to_atom(Out, In)
 1476    ;   to_atom(In, Out)
 1477    ).
 1478oas_type(binary, In, Out) :-
 1479    (   var(In)
 1480    ->  to_string(Out, In)
 1481    ;   to_string(In, Out)
 1482    ).
 1483oas_type(base64, In, Out) :-
 1484    base64(In, Out).
 1485oas_type(boolean, In, Out) :-
 1486    (   var(In)
 1487    ->  to_boolean(Out, In)
 1488    ;   to_boolean(In, Out)
 1489    ).
 1490oas_type(date, In, Out) :-
 1491    cvt_date_time(date, In, Out).
 1492oas_type(date_time, In, Out) :-
 1493    cvt_date_time(date_time, In, Out).
 1494oas_type(password, In, Out) :-
 1495    (   var(In)
 1496    ->  to_string(Out, In)
 1497    ;   to_string(In, Out)
 1498    ).

 cvt_date_time(+Format, ?In, ?Out) is det

Convert between wire (xsd) dateTime and Prolog. As Prolog input we accept a term (date(Y,M,D) or date_time(Y,M,D,H,Mn,S,0)), a time stamp or an xsd dateTime string.

 1506cvt_date_time(Format, In, Out) :-
 1507    (   var(In)
 1508    ->  (   (   atom(Out)
 1509            ->  to_string(Out, In)
 1510            ;   string(Out)
 1511            ->  In = Out
 1512            )
 1513        ->  valid_date_time(Format, In, _)
 1514        ;   compound(Out)
 1515        ->  valid_date_time(Format, In, Out)
 1516        ;   number(Out)
 1517        ->  stamp_date_time(Out, date(Y,M,D,H,Mn,S,0,_Tz,_Dst), 'UTC'),
 1518            (   Format = date_time
 1519            ->  valid_date_time(Format, In, date_time(Y,M,D,H,Mn,S,0))
 1520            ;   valid_date_time(Format, In, date(Y,M,D))
 1521            )
 1522        )
 1523    ;   valid_date_time(Format, In, Out) % creating a date/6 struct
 1524    ).
 1525
 1526valid_date_time(date, String, Date) :-
 1527    xsd_time_string(Date,  % date(Y,M,D)
 1528                    'http://www.w3.org/2001/XMLSchema#date',
 1529                    String).
 1530valid_date_time(date_time, String, DateTime) :-
 1531    xsd_time_string(DateTime,  % date_time(Y,M,D,H,Mi,S[,TZ])
 1532                    'http://www.w3.org/2001/XMLSchema#dateTime',
 1533                    String).
 1534
 1535cvt_integer(In, Out) :-
 1536    cvt_number(In, Out),
 1537    must_be(integer, Out).
 1538
 1539cvt_number(In, Out) :- nonvar(In), !, to_number(In, Out).
 1540cvt_number(N, N)    :- must_be(number, N).
 1541
 1542to_number(In, Out) :-
 1543    (   number(In)
 1544    ->  Out = In
 1545    ;   atom_number(In, Out0)
 1546    ->  Out = Out0
 1547    ;   type_error(number, In)
 1548    ).
 1549
 1550to_string(Val, String) :-
 1551    atom_string(Val, String).
 1552
 1553to_atom(Val, Atom) :-
 1554    atom_string(Atom, Val).
 1555
 1556to_boolean(Var, _) :-
 1557    var(Var),
 1558    !,
 1559    instantiation_error(Var).
 1560to_boolean(false,   false).
 1561to_boolean(true,    true).
 1562to_boolean('FALSE', false).
 1563to_boolean('TRUE',  true).
 1564to_boolean(0,       false).
 1565to_boolean(1,       true).
 1566to_boolean(no,      false).
 1567to_boolean(yes,     true).
 1568to_boolean('NO',    false).
 1569to_boolean('YES',   true).
 1570to_boolean(off,     false).
 1571to_boolean(on,      true).
 1572to_boolean('OFF',   false).
 1573to_boolean('ON',    true).