diff --git a/Sources/OpenAPIRuntime/Interface/ErrorHandlingMiddleware.swift b/Sources/OpenAPIRuntime/Interface/ErrorHandlingMiddleware.swift index 55113ce5..66ef3e03 100644 --- a/Sources/OpenAPIRuntime/Interface/ErrorHandlingMiddleware.swift +++ b/Sources/OpenAPIRuntime/Interface/ErrorHandlingMiddleware.swift @@ -74,7 +74,8 @@ public struct ErrorHandlingMiddleware: ServerMiddleware { /// /// Conform your error type to this protocol to convert it to an `HTTPResponse` and ``HTTPBody``. /// -/// Used by ``ErrorHandlingMiddleware``. +/// You must provide ``ErrorHandlingMiddleware`` to `registerHandlers` in order for +/// this value to get converted to the desired HTTP response. public protocol HTTPResponseConvertible { /// An HTTP status to return in the response. @@ -96,3 +97,36 @@ extension HTTPResponseConvertible { // swift-format-ignore: AllPublicDeclarationsHaveDocumentation public var httpBody: OpenAPIRuntime.HTTPBody? { nil } } + +/// An concrete error type that represents a desired HTTP response to be returned by the server. +/// +/// Throw this error in your API handler to return a specific undocumented HTTP response. +/// +/// You must provide ``ErrorHandlingMiddleware`` to `registerHandlers` in order for +/// this error to get converted to the desired HTTP response. +public struct HTTPResponseError: Error, HTTPResponseConvertible { + + /// An HTTP status to return in the response. + public var httpStatus: HTTPResponse.Status + + /// The HTTP header fields of the response. + public var httpHeaderFields: HTTPTypes.HTTPFields + + /// The body of the HTTP response. + public var httpBody: OpenAPIRuntime.HTTPBody? + + /// Creates a new error. + /// - Parameters: + /// - httpStatus: An HTTP status to return in the response. + /// - httpHeaderFields: The HTTP header fields of the response. + /// - httpBody: The body of the HTTP response. + public init( + httpStatus: HTTPResponse.Status, + httpHeaderFields: HTTPTypes.HTTPFields = [:], + httpBody: OpenAPIRuntime.HTTPBody? = nil + ) { + self.httpStatus = httpStatus + self.httpHeaderFields = httpHeaderFields + self.httpBody = httpBody + } +}