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            openapi_response/2                  % :PredicateName, Responses:list
   45          ]).   46:- use_module(library(apply)).   47:- use_module(library(apply_macros), []).   48:- use_module(library(debug)).   49:- use_module(library(option)).   50:- use_module(library(error)).   51:- use_module(library(base64)).   52:- use_module(library(sgml)).   53:- use_module(library(lists)).   54:- use_module(library(pairs)).   55:- use_module(library(yaml)).   56:- use_module(library(uri)).   57:- use_module(library(dcg/basics)).   58:- use_module(library(http/json)).   59:- use_module(library(http/http_json)).   60:- use_module(library(http/http_parameters)).   61:- use_module(library(http/http_header)).   62:- use_module(library(listing), [portray_clause/2, portray_clause/1]).   63:- use_module(library(pprint), [print_term/2]).   64:- use_module(library(http/http_open)).   65:- use_module(library(pcre), [re_match/3]).   66:- use_module(library(dcg/high_order), [sequence/5]).   67
   68                                                % generated code.

   78:- meta_predicate
   79    openapi_dispatch(:),
   80    openapi_arg(:, ?, ?, ?),
   81    openapi_response(:, -).

 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.

   90openapi_server(File, Options) :-
   91    throw(error(context_error(nodirective, openapi_server(File, Options)), _)).
   92
   93expand_openapi_server(File, Options,
   94                      [ (:- discontiguous((openapi_handler/11,
   95                                           openapi_doc/2))),
   96                        (:- multifile((openapi_error_hook/3)))
   97                      | Clauses
   98                      ]) :-
   99    read_openapi_spec(File, Spec, Options, Options1),
  100    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.

  109openapi_client(File, Options) :-
  110    throw(error(context_error(nodirective,
  111                              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.

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

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

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

 openapi_read(+File, -Term) is det

Read an OpenAPI specification file.

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

 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.

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

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

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

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

Generate documentation clauses for an operationId

  416path_docs(Method, Path, Spec,
  417          openapi_doc(OperationID, [path(Path)|Docs]),
  418          Options) :-
  419    handler_predicate(Method, Path, Spec, OperationID, [warn(false)|Options]),
  420    phrase(path_doc(Spec), Docs).

 path_doc(+Spec)//

Generate a list of documentation properties for Path

  426path_doc(Spec) -->
  427    path_doc(summary, Spec),
  428    path_doc(description, Spec),
  429    path_doc(tags, Spec).
  430
  431path_doc(Key, Spec) -->
  432    { Value = Spec.get(Key),
  433      !,
  434      Attr =.. [Key,Value]
  435    },
  436    [Attr].
  437path_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].

  450path_vars(PathSpec, Segments, Bindings) :-
  451    string_codes(PathSpec, Codes),
  452    phrase(path_vars(Segments, Bindings), Codes).
  453
  454path_vars([Segment,Var|Segments], [VarName=Var|Bindings]) -->
  455    string(SegCodes), "{", string(VarCodes), "}",
  456    !,
  457    { atom_codes(Segment, SegCodes),
  458      atom_codes(VarName, VarCodes)
  459    },
  460    path_vars(Segments, Bindings).
  461path_vars(Segments, []) -->
  462    remainder(Codes),
  463    {   Codes == []
  464    ->  Segments = []
  465    ;   atom_codes(Segment, Codes),
  466        Segments = [Segment]
  467    }.

 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.

  475match_path_list([], "").
  476match_path_list([Path], Path) :-
  477    !.
  478match_path_list([Atom], String) :-
  479    !,
  480    atom_string(Atom, String).
  481match_path_list([H|T], Path) :-
  482    nonvar(H),
  483    !,
  484    string_concat(H, Rest, Path),
  485    match_path_list(T, Rest).
  486match_path_list([V,H|T], Path) :-
  487    assertion(nonvar(H)),
  488    sub_string(Path, B, _, A, H),
  489    sub_string(Path, 0, B, _, V),
  490    sub_string(Path, _, A, 0, Rest),
  491    match_path_list(T, Rest),
  492    !.

 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.

  500content_parameter(Method, Spec, content(MediaType, Schema, Var, Descr),
  501                  Args, AllArgs, Options) :-
  502    has_content(Method),
  503    !,
  504    request_content_type(Spec, MediaType, Schema, Options),
  505    content_description(Spec, Descr),
  506    append(Args, [a(Var,'RequestBody',Schema)], AllArgs).
  507content_parameter(_, _, -, Args, Args, _).
  508
  509has_content(post).
  510has_content(put).
  511
  512content_description(JSON, Descr) :-
  513    Descr = JSON.get(requestBody).get(description),
  514    !.
  515content_description(_JSON, "").
  516
  517request_content_type(Spec, MediaType, Schema, Options) :-
  518    (   Body = Spec.get(requestBody)
  519    ->  true
  520    ;   Body = _{}
  521    ),
  522    !,
  523    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.

  540response(Result, Options, CodeA-Spec,
  541         response(Code, As, MediaType, Type, Result, Descr)) :-
  542    response_code(CodeA, Code, As),
  543    response_description(Spec, Descr),
  544    content_type(Spec, MediaType, Type, Options).
  545
  546response_code(default, _, error) :- !.
  547response_code(A, N, data) :-
  548    to_number(A, N).
  549
  550response_description(Spec, Descr) :-
  551    Descr = Spec.get(description),
  552    !.
  553response_description(_, "") .

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

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

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

 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.

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

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

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

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

 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.

  761response_has_data(Responses) :-
  762    maplist(arg(1), Responses, Codes),
  763    member(Code, Codes),
  764    \+ code_has_no_data(Code), !.
  765
  766code_has_no_data(Code) :-
  767    var(Code).                                  % errors
  768code_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,

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

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

Translate the request body into options for http_open/3.

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

 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.

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

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

 1000application_extra_query_parameters(Module, Method, Path, Extra) :-
 1001    current_predicate(Module:extra_query_parameters/3),
 1002    Module:extra_query_parameters(Method, Path, Extra),
 1003    !,
 1004    must_be(list, Extra).
 1005application_extra_query_parameters(_, _, _, []).

 array_query(Query)//

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

 1014array_query([]) --> [].
 1015array_query([Name=Value|T]) -->
 1016    (   {is_list(Value)}
 1017    ->  repeat_query(Value, Name)
 1018    ;   [Name=Value]
 1019    ),
 1020    array_query(T).
 1021
 1022repeat_query([], _) --> [].
 1023repeat_query([H|T], Name) -->
 1024    [ Name=H ],
 1025    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.

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

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

 1060client_header_param(_QOptions, hparam(Name, PlValue, Type, _Required),
 1061                    request_header(Name=Value)) :-
 1062    nonvar(PlValue),
 1063    !,
 1064    (   Type == any
 1065    ->  Value = PlValue
 1066    ;   json_check(Type, Value, PlValue)
 1067    ).
 1068client_header_param(QOptions, hparam(Name, _PlValue, Type, _Required),
 1069                    request_header(Name=Value)) :-
 1070    Opt =.. [Name,PlValue],
 1071    option(Opt, QOptions),
 1072    !,
 1073    json_check(Type, Value, PlValue).
 1074client_header_param(_QOptions, hparam(Name, _PlValue, _Type, required),
 1075                    _) :-
 1076    existence_error(openapi_option, Name).

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

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

 1083segment_value(Type, Segment, Prolog) :-
 1084    nonvar(Segment),
 1085    !,
 1086    uri_encoded(segment, Value, Segment),
 1087    json_check(Type, Value, Prolog).
 1088segment_value(Type, Segment, Prolog) :-
 1089    json_check(Type, Value, Prolog),
 1090    uri_encoded(segment, Value, Segment).

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

Handle the reply at the client side.

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

 assemble_security(+Security, +ClientModule, -HTTPOptions)

Assemble additional HTTP options from the security description.

 1148:- public assemble_security/3. 1149assemble_security(Security, CM, SecOptions) :-
 1150    current_predicate(CM:security_options/2),
 1151    CM:security_options(Security, SecOptions), !.
 1152assemble_security(Security, _, []) :-
 1153    memberchk(public, Security),
 1154    !.
 1155assemble_security(Security, _, _) :-
 1156    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.

 1170		 /*******************************
 1171		 *          DISPATCHER		*
 1172		 *******************************/

 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

 1183openapi_dispatch(M:Request) :-
 1184    memberchk(path(FullPath), Request),
 1185    memberchk(method(Method), Request),
 1186    M:openapi_root(Root),
 1187    atom_concat(Root, Path, FullPath),
 1188    M:openapi_handler(Method, PathList, Segments,
 1189                      Required, HdrParams, AsOption, OptionParam, Content,
 1190                      Responses, _Security,
 1191                      Handler),
 1192    match_path_list(PathList, Path),
 1193    !,
 1194    (   Error = error(_,_),
 1195        catch(openapi_run(M:Request,
 1196                          Segments,
 1197                          Required, HdrParams, AsOption, OptionParam, Content,
 1198                          Responses,
 1199                          Handler),
 1200              Error,
 1201              openapi_error(M, Error, Responses))
 1202    ->  true
 1203    ;   openapi_error(M, failed, Responses)
 1204    ).
 1205
 1206openapi_run(Module:Request,
 1207            Segments,
 1208            Required, HdrParams, AsOption, OptionParam, Content,
 1209            Responses,
 1210            Handler) :-
 1211    append(Required, AsOption, RequestParams),
 1212    IE = error(_,_),
 1213    catch(( maplist(segment_parameter, Segments),
 1214            maplist(header_parameter(Request), HdrParams),
 1215            http_parameters([method(get)|Request], RequestParams),
 1216            request_body(Content, Request),
 1217            server_handler_options(AsOption, OptionParam)
 1218          ), IE, input_error(IE, RequestParams)),
 1219    call(Module:Handler),
 1220    OE = error(_,_),
 1221    catch(openapi_reply(Module, Responses), OE,
 1222          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.

 1231input_error(error(Formal, Context), RequestParams) :-
 1232    subsumes_term(context(_, http_parameter(_)), Context),
 1233    Context = context(_, http_parameter(Param)),
 1234    debug(rest(error), 'Error in ~p; request = ~p', [Param, RequestParams]),
 1235    member(ReqParam, RequestParams),
 1236    ReqParam =.. [Param, _Value, Options],
 1237    http_param_type(Options, Type),
 1238    !,
 1239    throw(error(Formal, rest(Param, request, Type))).
 1240input_error(E, _RequestParams) :- throw(E).
 1241
 1242http_param_type(Options, Type) :-
 1243    memberchk(openapi(Type), Options),
 1244    !.
 1245http_param_type(Options, array(Type, _)) :-
 1246    memberchk(list(openapi(Type)), Options),
 1247    !.
 1248
 1249output_error(E) :- throw(E).
 1250
 1251:- meta_predicate
 1252    add_error_context(0, +). 1253
 1254add_error_context(Goal, C) :-
 1255    catch(Goal, error(Formal, _), throw(error(Formal, C))).

 segment_parameter(?Segment)

Fill a segment parameter

 1261segment_parameter(segment(Type, Segment, Value, Name, _Description)) :-
 1262    add_error_context(
 1263        segment_value(Type, Segment, Value),
 1264        rest(Name, path, Type)).
 1265
 1266server_handler_options([], []).
 1267server_handler_options([H|T], Options) :-
 1268    arg(1, H, Value),
 1269    (   var(Value)
 1270    ->  server_handler_options(T, Options)
 1271    ;   functor(H, Name, _),
 1272        Opt =.. [Name,Value],
 1273        Options = [Opt|OptT],
 1274        server_handler_options(T, OptT)
 1275    ).

 header_parameter(+Request, +HdrParam)

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

 1283header_parameter(Request, HdrParam) :-
 1284    HdrParam =.. [Name, Arg, _Opts],
 1285    Header =.. [Name,Arg],
 1286    (   memberchk(Header, Request)
 1287    ->  true
 1288    ;   print_message(warning, error(rest_error(missing_header(Name)), _))
 1289    ).

 request_body(+ContentSpec, +Request) is det

Read the specified request body.

 1295request_body(-, _).
 1296request_body(content(media(application/json,_), -, Body, _Descr), Request) :-
 1297    !,
 1298    add_error_context(
 1299        http_read_json_dict(Request, Body),
 1300        rest(body, request_body, json)).
 1301request_body(content(media(application/json,_), Type, Body, _Descr), Request) :-
 1302    add_error_context(
 1303        http_read_json_dict(Request, Body0),
 1304        rest(body, request_body, json)),
 1305    add_error_context(
 1306        json_check(Type, Body0, Body),
 1307        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.

 1326:- det(openapi_reply/2). 1327openapi_reply(Module, Responses) :-
 1328    Responses = [R0|_],
 1329    arg(5, R0, Reply),
 1330    reply_status(Reply, Code, Data),
 1331    memberchk(response(Code, _As, MediaType, Type, _, _Descr), Responses),
 1332    openapi_reply(Code, MediaType, Type, Data, Module).
 1333
 1334reply_status(Var, _, _) :-
 1335    var(Var), !,
 1336    instantiation_error(Var).
 1337reply_status(status(Code, Data), Code, Data) :- !.
 1338reply_status(status(Code), Code, '') :- !.
 1339reply_status(Data, 200, Data).

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

 1343:- det(openapi_reply/5). 1344openapi_reply(Code, _, _, '', _) :-
 1345    !,
 1346    format('Status: ~d~n~n', [Code]).
 1347openapi_reply(Code, media(application/json,_), -, Data, Module) :-
 1348    !,
 1349    Module:openapi_server_config(reply_json_options(Options)),
 1350    reply_json_dict(Data, [status(Code)|Options]).
 1351openapi_reply(Code, media(application/json,_), Type, Data, Module) :-
 1352    !,
 1353    (   Module:openapi_server_config(type_check_response(true))
 1354    ->  json_check(Type, Out, Data)
 1355    ;   Out = Data
 1356    ),
 1357    Module:openapi_server_config(reply_json_options(Options)),
 1358    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.

 1370openapi_error(Module, Error, Responses) :-
 1371    map_error(Module, Error, Responses, Reply),
 1372    Responses = [R0|_],
 1373    arg(5, R0, Reply),
 1374    openapi_reply(Module, Responses),
 1375    !.
 1376openapi_error(_Module, Error, _Responses) :-
 1377    throw(Error).
 1378
 1379map_error(Module, Error, Responses, Reply) :-
 1380    call(Module:openapi_error_hook(Error, Responses, Reply)),
 1381    !.
 1382map_error(_Module, Error, _Responses, Reply) :-
 1383    Error = error(_, Context),
 1384    nonvar(Context),
 1385    http_error_status(Context, Error, Status),
 1386    message_to_string(Error, Message),
 1387    Reply = status(Status, _{code:Status, message:Message}).
 1388
 1389http_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.

 1411		 /*******************************
 1412		 *            TYPES		*
 1413		 *******************************/

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

 1419api_type(Type, Format, TypeID) :-
 1420    api_type(_Name, Type, Format, TypeID), !.
 1421api_type(string, Format, string) :-
 1422    !,
 1423    print_message(warning, openapi(unknown_string_format, Format)).
 1424api_type(Type, Format, _TypeID) :-
 1425    print_message(error, openapi(unknown_type, Type, Format)),
 1426    fail.

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

The formats defined by the OAS are:

 1433api_type(integer,  integer,    int32,       int32).
 1434api_type(long,     integer,    int64,       int64).
 1435api_type(long,     integer,    -,           integer).
 1436api_type(float,    number,     float,       float).
 1437api_type(double,   number,     double,      float).
 1438api_type(double,   number,     -,           float).
 1439api_type(string,   string,     -,           string).
 1440api_type(byte,     string,     byte,        base64).
 1441api_type(binary,   string,     binary,      binary).
 1442api_type(boolean,  boolean,    -,           boolean).
 1443api_type(date,     string,     date,        date).
 1444api_type(dateTime, string,     'date-time', date_time).
 1445api_type(password, string,     password,    password).
 1446api_type(string,   string,     string,      string). % Not in OAS
 1447api_type(uri,      string,     uri,         uri).    % Not in OAS
 1448api_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.

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

 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.

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