Deal with different success responses #119

Activity

1. schlichtanders commented on Sep 17, 2026

   

   schlichtanders

   on Sep 17, 2026

   Last edited by schlichtanders

   Author

   More actions

   Here my current full workaround when including the OpenAPI generated Server. Works

   _replace_success_response(ex) = ex
   function _replace_success_response(ex::Expr)
       # _success_response(operation.responses) -> _response_by_type(operation.responses, result)
       if ex.head == :call && ex.args[1] == :_success_response
           return Expr(:call, :_response_by_type, ex.args[2], :result)
       end
       # Recursively process children
       return Expr(ex.head, map(_replace_success_response, ex.args)...)
   end
   include(_replace_success_response, "../../openapi/APIServer.jl")
   @eval APIServer begin
       function _response_by_type(responses, result)
           # first try to find type
           for response in responses
               for media in response.media
                   if media.type == typeof(result)
                       return response
                   end
               end
           end
           # fall back to default selector
           for response in responses
               selector = uppercase(response.selector)
               if selector == "DEFAULT"
                   return response
               end
           end
           # fall back to nothing
           return nothing
       end
   end

   Is a pullrequest welcome?
2. tanmaykm commented on Sep 19, 2026

   

   tanmaykm

   on Sep 19, 2026

   Member

   More actions

   Thanks for the clear report and the workaround. Yes, a PR is welcome. Some notes first so it lands in a shape we can keep.

   What happens today

   The generated server always picks the first documented 2xx response and encodes the returned value against it. So with

   responses:
     "200":
       content:
         application/json:
           schema: { $ref: "#/components/schemas/Done" }
     "202":
       content:
         application/json:
           schema: { $ref: "#/components/schemas/Accepted" }

   a handler that returns an Accepted is checked against the Done schema, and validation fails. That is what you are seeing.

   This is not new in 1.x. The 0.2 server did the same thing: any plain return value went out as a 200. What changed is that 1.x now validates the response body before sending it, so the mismatch shows up as an error instead of a 200 with the wrong body. We hit the same thing when porting our own services, and the answer so far has been the escape hatch that already exists: return an HTTP.Response yourself.

   function submit(request, body)
       if needs_processing(body)
           return HTTP.Response(202, ["Content-Type" => "application/json"], JSON.json(Accepted(...)))
       end
       return Done(...)   # encoded and validated as the 200
   end

   That works, but you lose validation for that branch and have to encode the body by hand. So we agree this deserves a proper fix.

   Why picking by type is not enough

   The _response_by_type idea works for your document, but it falls over in common cases:

   • Two statuses often document the same type. 200 and 201 both returning a Widget is normal.
   • Many responses are plain strings, byte arrays or free-form objects, so there is no type to tell them apart.
   • A handler returning a Dict or a Vector matches nothing, and the fallback to default would then send an error-shaped body as the status of the default response.

   So the status has to come from the handler, not be guessed from the value.

   Suggested shape

   Let the handler say the status explicitly, and keep everything else the same:

   function submit(request, body)
       if needs_processing(body)
           return OpenAPI.Reply(202, Accepted(...))   # name open for discussion
       end
       return Done(...)                                # plain value still means "first 2xx"
   end
   
   function get_item(request, id)
       item = lookup(id)
       item === nothing && return OpenAPI.Reply(404, ClientError(message = "no such item"))
       return item
   end

   _server_response then looks up the response for that status (exact code first, then 4XX-style ranges, then default, which the runtime already does for clients in _select_response), validates the value against that response's schema, and sends it with that status. A plain value keeps today's behaviour, so existing servers do not change. Returning an HTTP.Response stays as the escape hatch for anything else.

   This covers both of your cases, the 202 and the 400, with one mechanism, and the body is still validated.

   What the PR would need

   • The wrapper type in the runtime and the status lookup in the generated _server_response.
   • A clear error when the status is not documented for that operation.
   • A round-trip test in test/servergen.jl with a 200/202 pair and a 4xx typed error.
   • A short section in docs/src/servers.md with an example like the one above.

   One more thing worth fixing on the way: the generated handler signature lists the union of all documented body types as the return type. That reads as if the server dispatches on the type, which it does not, and it is probably part of why the type-based fix looked natural. Happy to discuss the wrapper's name and whether a (status, value) tuple would be nicer than a struct.

   ❤️React with ❤️1Reacted by Stephan Sahm
3. tanmaykm

   closed this as completedin #129on Sep 28, 2026
4. tanmaykm

   added a commit that references this issue on Sep 29, 2026

   increment minor version to 1.2.0 (#130)

   dc7d63c