Add query params, function docs, and configurable OpenAPI metadata

rebar.config

@@ -18,7 +18,7 @@
 
 {deps, [
     {elli, "~> 3.3.0"},
-    {spectra, "~> 0.4.0"}
+    {spectra, "~> 0.8.2"}
 ]}.
 
 {hank, [

rebar.lock

@@ -5,12 +5,12 @@
               {ref,"c4d1098174cec06bd124855f3a28dfd6eda0a581"},
               "eqwalizer_support"},
   0},
- {<<"spectra">>,{pkg,<<"spectra">>,<<"0.4.0">>},0}]}.
+ {<<"spectra">>,{pkg,<<"spectra">>,<<"0.8.2">>},0}]}.
 [
 {pkg_hash,[
  {<<"elli">>, <<"089218762A7FF3D20AE81C8E911BD0F73EE4EE0ED85454226D1FC6B4FFF3B4F6">>},
- {<<"spectra">>, <<"1A5390E55B34F83693998FD7ECBC448BCDC5FC5EBCCA790C7B0DD2D6A0FED255">>}]},
+ {<<"spectra">>, <<"6BDFBB85624628B6F8537A27B0185004713349C908505DD1D9E288AFAE435EDF">>}]},
 {pkg_hash_ext,[
  {<<"elli">>, <<"698B13B33D05661DB9FE7EFCBA41B84825A379CCE86E486CF6AFF9285BE0CCF8">>},
- {<<"spectra">>, <<"E51E88BE6EB3B85A1E3D0A9651A9F76ACA5A83A1EF940467541B77D078C5FB84">>}]}
+ {<<"spectra">>, <<"298134F7564A7EA1152FF205927E5D8BB5FCD4845E5A5BE18F87C75D74368303">>}]}
 ].

src/elli_openapi.erl

@@ -2,6 +2,7 @@
 
 -export([
     setup_routes/1,
+    setup_routes/2,
     route_call/1,
     to_handler_type/1,
     to_endpoint/2,
@@ -27,15 +28,20 @@
 -record(handler_type, {
     mfa :: mfa(),
     path_args :: #sp_map{},
+    query_args :: #sp_map{},
     header_args :: #sp_map{},
     request_body :: spectra:sp_type(),
     request_content_type :: content_type(),
-    responses :: #{integer() => #response_spec{}}
+    responses :: #{integer() => #response_spec{}},
+    doc :: spectra:function_doc()
 }).
 
 -type spectra_openapi__endpoint_spec() :: map().
 
 setup_routes(Routes) ->
+    setup_routes(#{title => ~"My API", version => ~"1.0.0"}, Routes).
+
+setup_routes(MetaData, Routes) ->
     RouteEndpoints =
         lists:map(
             fun(Route) ->
@@ -44,7 +50,6 @@ setup_routes(Routes) ->
             end,
             Routes
         ),
-    MetaData = #{title => ~"My API", version => ~"1.0.0"},
     {ok, OpenApiSpec} = generate_openapi_spec(MetaData, Routes),
     OpenApiJson = json:encode(OpenApiSpec),
     Mref = to_matchspec(RouteEndpoints),
@@ -61,8 +66,8 @@ route_call(ElliRequest) ->
             HttpPathArgs = maps:from_list(HttpPathArgsList),
             {Fun, _Endpoint, HandlerType} = maps:get({Method, RoutePath}, MyMap),
             case check_types(HandlerType, HttpPathArgs, ElliRequest) of
-                {ok, PathArgs, Headers, Body} ->
-                    Response = Fun(PathArgs, Headers, Body),
+                {ok, PathArgs, QueryArgs, Headers, Body} ->
+                    Response = Fun(PathArgs, QueryArgs, Headers, Body),
                     check_and_convert_response(HandlerType, Response);
                 {error, ErldanticErrors} ->
                     {400, [], spectra_error_to_response_body(ErldanticErrors)}
@@ -150,27 +155,18 @@ check_types(HandlerType, PathArgs, ElliRequest) ->
     #handler_type{
         mfa = {Module, _, _},
         path_args = PathArgsType,
+        query_args = QueryArgsType,
         header_args = HeadersType,
         request_body = RequestBodyType,
         request_content_type = RequestContentType
-    } =
-        HandlerType,
-
-    case decode_path_args(Module, PathArgs, PathArgsType) of
-        {ok, DecodePathArgs} ->
-            case decode_headers(Module, HeadersType, elli_request:headers(ElliRequest)) of
-                {ok, DecodedHeader} ->
-                    case decode_body(Module, RequestBodyType, RequestContentType, ElliRequest) of
-                        {ok, DecodedBody} ->
-                            {ok, DecodePathArgs, DecodedHeader, DecodedBody};
-                        {error, _} = Error ->
-                            Error
-                    end;
-                {error, _} = Error ->
-                    Error
-            end;
-        {error, _} = Error ->
-            Error
+    } = HandlerType,
+    maybe
+        {ok, DecodedPathArgs} ?= decode_path_args(Module, PathArgs, PathArgsType),
+        {ok, DecodedQueryArgs} ?= decode_query_args(Module, QueryArgsType, ElliRequest),
+        {ok, DecodedHeaders} ?=
+            decode_headers(Module, HeadersType, elli_request:headers(ElliRequest)),
+        {ok, DecodedBody} ?= decode_body(Module, RequestBodyType, RequestContentType, ElliRequest),
+        {ok, DecodedPathArgs, DecodedQueryArgs, DecodedHeaders, DecodedBody}
     end.
 
 decode_body(Module, RequestBodyType, ExpectedContentType, ElliRequest) ->
@@ -227,6 +223,33 @@ decode_path_args(Module, PathArgs, PathArgsType) ->
         PathArgsType#sp_map.fields
     ).
 
+decode_query_args(Module, QueryArgsType, ElliRequest) ->
+    QueryParams = elli_request:get_args(ElliRequest),
+    spectra_util:fold_until_error(
+        fun(
+            #literal_map_field{
+                kind = Kind, name = FieldName, binary_name = BinaryName, val_type = Type
+            },
+            Acc
+        ) ->
+            case lists:keyfind(BinaryName, 1, QueryParams) of
+                {BinaryName, ParamValue} ->
+                    case spectra:decode(binary_string, Module, Type, ParamValue) of
+                        {ok, DecodedParam} ->
+                            {ok, Acc#{FieldName => DecodedParam}};
+                        {error, _} = Error ->
+                            Error
+                    end;
+                false when Kind =:= exact ->
+                    {error, {missing_query_param, FieldName}};
+                false ->
+                    {ok, Acc}
+            end
+        end,
+        #{},
+        QueryArgsType#sp_map.fields
+    ).
+
 decode_headers(Module, HeadersType, Headers) ->
     spectra_util:fold_until_error(
         fun(
@@ -280,27 +303,42 @@ to_endpoint(
     #handler_type{
         mfa = {Module, _Function, _Arity},
         path_args = PathArgs,
+        query_args = QueryArgs,
         header_args = HeaderArgs,
         request_body = RequestBody,
         request_content_type = RequestContentType,
-        responses = Responses
+        responses = Responses,
+        doc = FunctionDoc
     }
 ) ->
-    Endpoint0 = spectra_openapi:endpoint(to_spectra_http_method(HttpMethod), Path),
+    EndpointDoc = maps:with([summary, description, deprecated], FunctionDoc),
+    Endpoint0 = spectra_openapi:endpoint(to_spectra_http_method(HttpMethod), Path, EndpointDoc),
     PathFun =
         fun(Key, Val, EndpointAcc) ->
             PathArg =
                 #{
                     name => Key,
                     in => path,
                     required => true,
-                    module => Module,
                     schema => Val
                 },
-
             spectra_openapi:with_parameter(EndpointAcc, Module, PathArg)
         end,
     EndpointWithPath = maps:fold(PathFun, Endpoint0, to_map(PathArgs)),
+    QueryFun =
+        fun(
+            #literal_map_field{kind = Kind, binary_name = BinaryName, val_type = Type}, EndpointAcc
+        ) ->
+            QueryArg =
+                #{
+                    name => BinaryName,
+                    in => query,
+                    required => Kind =:= exact,
+                    schema => Type
+                },
+            spectra_openapi:with_parameter(EndpointAcc, Module, QueryArg)
+        end,
+    EndpointWithQuery = lists:foldl(QueryFun, EndpointWithPath, QueryArgs#sp_map.fields),
     HeaderFun =
         fun(
             #literal_map_field{kind = Kind, binary_name = BinaryName, val_type = Type}, EndpointAcc
@@ -310,12 +348,11 @@ to_endpoint(
                     name => BinaryName,
                     in => header,
                     required => Kind =:= exact,
-                    module => Module,
                     schema => Type
                 },
             spectra_openapi:with_parameter(EndpointAcc, Module, HeaderArg)
         end,
-    EndpointWithHeaders = lists:foldl(HeaderFun, EndpointWithPath, HeaderArgs#sp_map.fields),
+    EndpointWithHeaders = lists:foldl(HeaderFun, EndpointWithQuery, HeaderArgs#sp_map.fields),
 
     %% Only add request body for HTTP methods that support it
     Endpoint1 =
@@ -405,7 +442,7 @@ generate_openapi_spec(MetaData, Routes) ->
         ),
     Endpoints =
         lists:map(fun({_Route, Endpoint, _HandlerType}) -> Endpoint end, RouteEndpoints),
-    spectra_openapi:endpoints_to_openapi(MetaData, Endpoints).
+    spectra_openapi:endpoints_to_openapi(MetaData, Endpoints, [pre_encoded]).
 
 -spec infer_content_type(spectra:sp_type()) -> content_type().
 infer_content_type(#sp_simple_type{type = binary}) ->
@@ -451,20 +488,33 @@ join_function_specs(
     MFA,
     [
         #sp_function_spec{
-            args = [PathArgs, HeaderArgs, Body],
-            return = ReturnType
+            args = [PathArgs, QueryArgs, HeaderArgs, Body],
+            return = ReturnType,
+            meta = Meta
         }
     ]
 ) ->
     Responses = extract_responses(ReturnType),
+    Doc = maps:get(doc, Meta, #{}),
     #handler_type{
         mfa = MFA,
         path_args = PathArgs,
+        query_args = QueryArgs,
         header_args = HeaderArgs,
         request_body = Body,
         request_content_type = infer_content_type(Body),
-        responses = Responses
-    }.
+        responses = Responses,
+        doc = Doc
+    };
+join_function_specs({Module, Function, Arity}, [#sp_function_spec{args = Args}]) ->
+    erlang:error(
+        {handler_wrong_arity, #{
+            mfa => {Module, Function, Arity},
+            expected_args => 4,
+            got_args => length(Args),
+            hint => ~"Handler spec must be: (PathArgs, QueryArgs, Headers, Body) -> Response"
+        }}
+    ).
 
 %% Extract response specifications from return type
 %% Handles both single tuple: {200, Headers, Body}