handle multiple (per resp code) return types (#3)

* handle multiple (per resp code) return types

Implements a way to handle per HTTP response code return types.

* also return http response from client api call

Author: tanmaykm

README.md

@@ -63,20 +63,25 @@ Validations are imposed in the constructor and `setproperty!` methods of models.
 
 Each client API set is generated into a file named `api_<apiname>.jl`. It is represented as a `struct` and the APIs under it are generated as methods. An API set can be constructed by providing the OpenAPI client instance that it can use for communication.
 
-The required API parameters are generated as regular function arguments. Optional parameters are generated as keyword arguments. Method documentation is generated with description, parameter information and return value. Two variants of the API are generated. The first variant is suitable for calling synchronously and returns a single instance of the result struct.
+The required API parameters are generated as regular function arguments. Optional parameters are generated as keyword arguments. Method documentation is generated with description, parameter information and return value. Two variants of the API are generated. The first variant is suitable for calling synchronously. It returns a tuple of the result struct and the HTTP response.
 
 ```julia
 # example synchronous API that returns an Order instance
-getOrderById(api::StoreApi, orderId::Int64)
+getOrderById(api::StoreApi, orderId::Int64) -> (result, http_response)
 ```
 
 The second variant is suitable for asynchronous calls to methods that return chunked transfer encoded responses, where in the API streams the response objects into an output channel.
 
 ```julia
 # example asynchronous API that streams matching Pet instances into response_stream
-findPetsByStatus(api::PetApi, response_stream::Channel, status::Vector{String})
+findPetsByStatus(api::PetApi, response_stream::Channel, status::Vector{String}) -> (response_stream, http_response)
 ```
 
+The HTTP response returned from the API calls, have these properties:
+- `status`: integer status code
+- `message`: http message corresponding to status code
+- `headers`: http response headers as `Vector{Pair{String,String}}`
+
 A client context holds common information to be used across APIs. It also holds a connection to the server and uses that across API calls.
 The client context needs to be passed as the first parameter of all API calls. It can be created as:
 

src/client.jl

@@ -9,7 +9,7 @@ using TimeZones
 using LibCURL
 
 import Base: convert, show, summary, getproperty, setproperty!, iterate
-import ..OpenAPI: APIModel, APIClientImpl, OpenAPIException, to_json, from_json, validate_property, property_type
+import ..OpenAPI: APIModel, APIClientImpl, OpenAPIException, InvocationException, to_json, from_json, validate_property, property_type
 import ..OpenAPI: str2zoneddatetime, str2datetime, str2date
 
 # collection formats (OpenAPI v2)
@@ -42,6 +42,50 @@ struct ApiException <: Exception
     end
 end
 
+"""
+Represents the raw HTTP provol response from the server.
+Properties available:
+- status: the HTTP status code
+- message: the HTTP status message
+- headers: the HTTP headers
+- raw: the raw response ( as a Downloads.Response object)
+"""
+struct ApiResponse
+    raw::Downloads.Response
+end
+
+function Base.getproperty(resp::ApiResponse, name::Symbol)
+    raw = getfield(resp, :raw)
+    if name === :status
+        return raw.status
+    elseif name === :message
+        return raw.message
+    elseif name === :headers
+        return raw.headers
+    else
+        return getfield(resp, name)
+    end
+end
+
+function get_api_return_type(return_types::Dict{Regex,Type}, ::Nothing, response_data::String)
+    # this is the async case, where we do not have the response code yet
+    # in such cases we look for the 200 response code 
+    return get_api_return_type(return_types, 200, response_data)
+end
+function get_api_return_type(return_types::Dict{Regex,Type}, response_code::Integer, response_data::String)
+    default_response_code = 0
+    for code in string.([response_code, default_response_code])
+        for (re, rt) in return_types
+            if match(re, code) !== nothing
+                return rt
+            end
+        end
+    end
+    # if no specific return type was defined, we assume that:
+    # - if response code is 2xx, then we make the method call return nothing
+    # - otherwise we make it throw an ApiException
+    return (200 <= response_code <=206) ? Nothing : nothing # first(return_types)[2]
+end
 struct Client
     root::String
     headers::Dict{String,String}
@@ -54,7 +98,7 @@ struct Client
 
     function Client(root::String;
             headers::Dict{String,String}=Dict{String,String}(),
-            get_return_type::Function=(default,data)->default,
+            get_return_type::Function=get_api_return_type,
             long_polling_timeout::Int=DEFAULT_LONGPOLL_TIMEOUT_SECS,
             timeout::Int=DEFAULT_TIMEOUT_SECS,
             pre_request_hook::Function=noop_pre_request_hook)
@@ -96,7 +140,7 @@ end
 struct Ctx
     client::Client
     method::String
-    return_type::Type
+    return_types::Dict{Regex,Type}
     resource::String
     auth::Vector{String}
 
@@ -110,12 +154,13 @@ struct Ctx
     curl_mime_upload::Ref{Any}
     pre_request_hook::Function
 
-    function Ctx(client::Client, method::String, return_type, resource::String, auth, body=nothing;
+    function Ctx(client::Client, method::String, return_types::Dict{Regex,Type}, resource::String, auth, body=nothing;
             timeout::Int=client.timeout[],
-            pre_request_hook::Function=client.pre_request_hook)
+            pre_request_hook::Function=client.pre_request_hook,
+        )
         resource = client.root * resource
         headers = copy(client.headers)
-        new(client, method, return_type, resource, auth, Dict{String,String}(), Dict{String,String}(), headers, Dict{String,String}(), Dict{String,String}(), body, timeout, Ref{Any}(nothing), pre_request_hook)
+        new(client, method, return_types, resource, auth, Dict{String,String}(), Dict{String,String}(), headers, Dict{String,String}(), Dict{String,String}(), body, timeout, Ref{Any}(nothing), pre_request_hook)
     end
 end
 
@@ -325,7 +370,7 @@ function do_request(ctx::Ctx, stream::Bool=false; stream_to::Union{Channel,Nothi
                 @async begin
                     try
                         for chunk in ChunkReader(output)
-                            return_type = ctx.client.get_return_type(ctx.return_type, String(copy(chunk)))
+                            return_type = ctx.client.get_return_type(ctx.return_types, nothing, String(copy(chunk)))
                             data = response(return_type, resp, chunk)
                             put!(stream_to, data)
                         end
@@ -377,19 +422,22 @@ function exec(ctx::Ctx, stream_to::Union{Channel,Nothing}=nothing)
 
     if resp === nothing
         # request was interrupted
-        return nothing
+        throw(InvocationException("request was interrupted"))
     end
 
-    if isa(resp, Downloads.RequestError) || !(200 <= resp.status <= 206)
+    if isa(resp, Downloads.RequestError)
         throw(ApiException(resp))
     end
 
     if stream
-        return resp
+        return stream_to, ApiResponse(resp)
     else
         data = read(output)
-        return_type = ctx.client.get_return_type(ctx.return_type, String(copy(data)))
-        return response(return_type, resp, data)
+        return_type = ctx.client.get_return_type(ctx.return_types, resp.status, String(copy(data)))
+        if isnothing(return_type)
+            return nothing, ApiResponse(resp)
+        end
+        return response(return_type, resp, data), ApiResponse(resp)
     end
 end
 

src/commontypes.jl

@@ -6,5 +6,8 @@ end
 struct ValidationException <: Exception
     reason::String
 end
+struct InvocationException <: Exception
+    reason::String
+end
 
 property_type(::Type{T}, name::Symbol) where {T<:APIModel} = error("invalid type $T")

test/client/petstore_v2/petstore/.openapi-generator/VERSION

@@ -1 +1 @@
-6.1.0-SNAPSHOT
+6.2.1-SNAPSHOT

test/client/petstore_v2/petstore/docs/PetApi.md

@@ -15,8 +15,8 @@ Method | HTTP request | Description
 
 
 # **add_pet**
-> add_pet(_api::PetApi, body::Pet; _mediaType=nothing) <br/>
-> add_pet(_api::PetApi, response_stream::Channel, body::Pet; _mediaType=nothing)
+> add_pet(_api::PetApi, body::Pet; _mediaType=nothing) -> Nothing, OpenAPI.Clients.ApiResponse <br/>
+> add_pet(_api::PetApi, response_stream::Channel, body::Pet; _mediaType=nothing) -> Channel{ Nothing }, OpenAPI.Clients.ApiResponse
 
 Add a new pet to the store
 
@@ -29,7 +29,7 @@ Name | Type | Description  | Notes
 
 ### Return type
 
- nothing
+Nothing
 
 ### Authorization
 
@@ -43,8 +43,8 @@ Name | Type | Description  | Notes
 [[Back to top]](#) [[Back to API list]](../README.md#documentation-for-api-endpoints) [[Back to Model list]](../README.md#documentation-for-models) [[Back to README]](../README.md)
 
 # **delete_pet**
-> delete_pet(_api::PetApi, pet_id::Int64; api_key=nothing, _mediaType=nothing) <br/>
-> delete_pet(_api::PetApi, response_stream::Channel, pet_id::Int64; api_key=nothing, _mediaType=nothing)
+> delete_pet(_api::PetApi, pet_id::Int64; api_key=nothing, _mediaType=nothing) -> Nothing, OpenAPI.Clients.ApiResponse <br/>
+> delete_pet(_api::PetApi, response_stream::Channel, pet_id::Int64; api_key=nothing, _mediaType=nothing) -> Channel{ Nothing }, OpenAPI.Clients.ApiResponse
 
 Deletes a pet
 
@@ -63,7 +63,7 @@ Name | Type | Description  | Notes
 
 ### Return type
 
- nothing
+Nothing
 
 ### Authorization
 
@@ -77,8 +77,8 @@ Name | Type | Description  | Notes
 [[Back to top]](#) [[Back to API list]](../README.md#documentation-for-api-endpoints) [[Back to Model list]](../README.md#documentation-for-models) [[Back to README]](../README.md)
 
 # **find_pets_by_status**
-> find_pets_by_status(_api::PetApi, status::Vector{String}; _mediaType=nothing) -> Vector{Pet}  <br/>
-> find_pets_by_status(_api::PetApi, response_stream::Channel, status::Vector{String}; _mediaType=nothing) -> Vector{Pet} 
+> find_pets_by_status(_api::PetApi, status::Vector{String}; _mediaType=nothing) -> Vector{Pet}, OpenAPI.Clients.ApiResponse <br/>
+> find_pets_by_status(_api::PetApi, response_stream::Channel, status::Vector{String}; _mediaType=nothing) -> Channel{ Vector{Pet} }, OpenAPI.Clients.ApiResponse
 
 Finds Pets by status
 
@@ -107,8 +107,8 @@ Name | Type | Description  | Notes
 [[Back to top]](#) [[Back to API list]](../README.md#documentation-for-api-endpoints) [[Back to Model list]](../README.md#documentation-for-models) [[Back to README]](../README.md)
 
 # **find_pets_by_tags**
-> find_pets_by_tags(_api::PetApi, tags::Vector{String}; _mediaType=nothing) -> Vector{Pet}  <br/>
-> find_pets_by_tags(_api::PetApi, response_stream::Channel, tags::Vector{String}; _mediaType=nothing) -> Vector{Pet} 
+> find_pets_by_tags(_api::PetApi, tags::Vector{String}; _mediaType=nothing) -> Vector{Pet}, OpenAPI.Clients.ApiResponse <br/>
+> find_pets_by_tags(_api::PetApi, response_stream::Channel, tags::Vector{String}; _mediaType=nothing) -> Channel{ Vector{Pet} }, OpenAPI.Clients.ApiResponse
 
 Finds Pets by tags
 
@@ -137,8 +137,8 @@ Name | Type | Description  | Notes
 [[Back to top]](#) [[Back to API list]](../README.md#documentation-for-api-endpoints) [[Back to Model list]](../README.md#documentation-for-models) [[Back to README]](../README.md)
 
 # **get_pet_by_id**
-> get_pet_by_id(_api::PetApi, pet_id::Int64; _mediaType=nothing) -> Pet  <br/>
-> get_pet_by_id(_api::PetApi, response_stream::Channel, pet_id::Int64; _mediaType=nothing) -> Pet 
+> get_pet_by_id(_api::PetApi, pet_id::Int64; _mediaType=nothing) -> Pet, OpenAPI.Clients.ApiResponse <br/>
+> get_pet_by_id(_api::PetApi, response_stream::Channel, pet_id::Int64; _mediaType=nothing) -> Channel{ Pet }, OpenAPI.Clients.ApiResponse
 
 Find pet by ID
 
@@ -167,8 +167,8 @@ Name | Type | Description  | Notes
 [[Back to top]](#) [[Back to API list]](../README.md#documentation-for-api-endpoints) [[Back to Model list]](../README.md#documentation-for-models) [[Back to README]](../README.md)
 
 # **update_pet**
-> update_pet(_api::PetApi, body::Pet; _mediaType=nothing) <br/>
-> update_pet(_api::PetApi, response_stream::Channel, body::Pet; _mediaType=nothing)
+> update_pet(_api::PetApi, body::Pet; _mediaType=nothing) -> Nothing, OpenAPI.Clients.ApiResponse <br/>
+> update_pet(_api::PetApi, response_stream::Channel, body::Pet; _mediaType=nothing) -> Channel{ Nothing }, OpenAPI.Clients.ApiResponse
 
 Update an existing pet
 
@@ -181,7 +181,7 @@ Name | Type | Description  | Notes
 
 ### Return type
 
- nothing
+Nothing
 
 ### Authorization
 
@@ -195,8 +195,8 @@ Name | Type | Description  | Notes
 [[Back to top]](#) [[Back to API list]](../README.md#documentation-for-api-endpoints) [[Back to Model list]](../README.md#documentation-for-models) [[Back to README]](../README.md)
 
 # **update_pet_with_form**
-> update_pet_with_form(_api::PetApi, pet_id::Int64; name=nothing, status=nothing, _mediaType=nothing) <br/>
-> update_pet_with_form(_api::PetApi, response_stream::Channel, pet_id::Int64; name=nothing, status=nothing, _mediaType=nothing)
+> update_pet_with_form(_api::PetApi, pet_id::Int64; name=nothing, status=nothing, _mediaType=nothing) -> Nothing, OpenAPI.Clients.ApiResponse <br/>
+> update_pet_with_form(_api::PetApi, response_stream::Channel, pet_id::Int64; name=nothing, status=nothing, _mediaType=nothing) -> Channel{ Nothing }, OpenAPI.Clients.ApiResponse
 
 Updates a pet in the store with form data
 
@@ -216,7 +216,7 @@ Name | Type | Description  | Notes
 
 ### Return type
 
- nothing
+Nothing
 
 ### Authorization
 
@@ -230,8 +230,8 @@ Name | Type | Description  | Notes
 [[Back to top]](#) [[Back to API list]](../README.md#documentation-for-api-endpoints) [[Back to Model list]](../README.md#documentation-for-models) [[Back to README]](../README.md)
 
 # **upload_file**
-> upload_file(_api::PetApi, pet_id::Int64; additional_metadata=nothing, file=nothing, _mediaType=nothing) -> ApiResponse  <br/>
-> upload_file(_api::PetApi, response_stream::Channel, pet_id::Int64; additional_metadata=nothing, file=nothing, _mediaType=nothing) -> ApiResponse 
+> upload_file(_api::PetApi, pet_id::Int64; additional_metadata=nothing, file=nothing, _mediaType=nothing) -> ApiResponse, OpenAPI.Clients.ApiResponse <br/>
+> upload_file(_api::PetApi, response_stream::Channel, pet_id::Int64; additional_metadata=nothing, file=nothing, _mediaType=nothing) -> Channel{ ApiResponse }, OpenAPI.Clients.ApiResponse
 
 uploads an image
 

test/client/petstore_v2/petstore/docs/StoreApi.md

@@ -11,8 +11,8 @@ Method | HTTP request | Description
 
 
 # **delete_order**
-> delete_order(_api::StoreApi, order_id::Int64; _mediaType=nothing) <br/>
-> delete_order(_api::StoreApi, response_stream::Channel, order_id::Int64; _mediaType=nothing)
+> delete_order(_api::StoreApi, order_id::Int64; _mediaType=nothing) -> Nothing, OpenAPI.Clients.ApiResponse <br/>
+> delete_order(_api::StoreApi, response_stream::Channel, order_id::Int64; _mediaType=nothing) -> Channel{ Nothing }, OpenAPI.Clients.ApiResponse
 
 Delete purchase order by ID
 
@@ -27,7 +27,7 @@ Name | Type | Description  | Notes
 
 ### Return type
 
- nothing
+Nothing
 
 ### Authorization
 
@@ -41,8 +41,8 @@ No authorization required
 [[Back to top]](#) [[Back to API list]](../README.md#documentation-for-api-endpoints) [[Back to Model list]](../README.md#documentation-for-models) [[Back to README]](../README.md)
 
 # **get_inventory**
-> get_inventory(_api::StoreApi; _mediaType=nothing) -> Dict{String, Int64}  <br/>
-> get_inventory(_api::StoreApi, response_stream::Channel; _mediaType=nothing) -> Dict{String, Int64} 
+> get_inventory(_api::StoreApi; _mediaType=nothing) -> Dict{String, Int64}, OpenAPI.Clients.ApiResponse <br/>
+> get_inventory(_api::StoreApi, response_stream::Channel; _mediaType=nothing) -> Channel{ Dict{String, Int64} }, OpenAPI.Clients.ApiResponse
 
 Returns pet inventories by status
 
@@ -67,8 +67,8 @@ This endpoint does not need any parameter.
 [[Back to top]](#) [[Back to API list]](../README.md#documentation-for-api-endpoints) [[Back to Model list]](../README.md#documentation-for-models) [[Back to README]](../README.md)
 
 # **get_order_by_id**
-> get_order_by_id(_api::StoreApi, order_id::Int64; _mediaType=nothing) -> Order  <br/>
-> get_order_by_id(_api::StoreApi, response_stream::Channel, order_id::Int64; _mediaType=nothing) -> Order 
+> get_order_by_id(_api::StoreApi, order_id::Int64; _mediaType=nothing) -> Order, OpenAPI.Clients.ApiResponse <br/>
+> get_order_by_id(_api::StoreApi, response_stream::Channel, order_id::Int64; _mediaType=nothing) -> Channel{ Order }, OpenAPI.Clients.ApiResponse
 
 Find purchase order by ID
 
@@ -97,8 +97,8 @@ No authorization required
 [[Back to top]](#) [[Back to API list]](../README.md#documentation-for-api-endpoints) [[Back to Model list]](../README.md#documentation-for-models) [[Back to README]](../README.md)
 
 # **place_order**
-> place_order(_api::StoreApi, body::Order; _mediaType=nothing) -> Order  <br/>
-> place_order(_api::StoreApi, response_stream::Channel, body::Order; _mediaType=nothing) -> Order 
+> place_order(_api::StoreApi, body::Order; _mediaType=nothing) -> Order, OpenAPI.Clients.ApiResponse <br/>
+> place_order(_api::StoreApi, response_stream::Channel, body::Order; _mediaType=nothing) -> Channel{ Order }, OpenAPI.Clients.ApiResponse
 
 Place an order for a pet