Response DSL type

[tdeleon]

Add a Response type to describe valid responses for an Operation.
See https://spec.openapis.org/oas/v3.2.0.html#responses-object.

Properties

Name	Type	Description
summary	String?	Optional short summary, used for comment doc generation
description	String?	Optional longer description, used for comment doc generation
httpStatus	HTTPResponse.Status?	The status that this response is valid for
kind	HTTPResponse.Status.Kind?	An alternative to a specific status, a kind of status (i.e. .clientError) that the response is expected
accept	HTTPField.MediaType?	The media type, if any, to be sent as an Accept header on the request for this response
content	Payload	The type of content expected in this response

Status & Kind

Responses are defined for a given HTTP status code or kind of status (range). In generated code, if a response is with a status other than those listed, an error will be thrown.

Default Status

Similar to the OpenAPI spec, a default response can be defined, that covers any status not otherwise explicitly defined with a response.

Response types

A response can have an expected type, or no content expected. The possible expected types are:

• JSON with a Decodable type
• JSON dictionary (returning [String: Any])
• Text (with an encoding)
• Data
• No content (returns a discardable result HTTPResponse)

For each of the cases, if the expected type does not match what is actually returned, an error is thrown in the generated code. The exception is no content, which does not attempt to validate what is returned, aside from the status code.

Static Functions

Factory static functions are provided to cover each of the response types (with a variant for an expected status, code, or kind), and an initializer for when no content is expected:

• json()
• jsonDictionary()
• text()
• data
• init()

Additionally, "default" static functions are provided for when the response is valid for any http status:

• defaultWithJSON()
• defaultWithJSONDictionary()
• defaultWithText()
• defaultWithData()
• default()

Accept Headers

By default, generated code will add the typical Accept header for each type, unless otherwise overridden.

Response Type	Default Media Type
JSON	application/json
JSONDictionary	application/json
Text	text/plain
Data	application/octet-stream
No Content	None (Accept not sent)

Each static factory or init has an optional accept parameter, which takes an HTTPField.MediaType, and defaults to the value above, depending on the response type. A custom type can be passed in to override this, or nil can be passed to omit sending the Accept header at all.

Examples

A response for 200/OK status, expecting a decodable type User. Generated function returns (User, HTTPResponse)

Response.json(.ok, returning: User.self, summary: "A valid user") {
    "A longer description about this response that returns a valid user."
}

A response for status code 500, expecting a JSON dictionary. Generated function returns ([String: Any], HTTPResponse).

Response.jsonDictionary(code: 500, summary: "500 Error") {
    "An error response returning a JSON dictionary"
}

A response for all client errors, not expecting any content. Generated function returns a discardable result of HTTPResponse.

Response(kind: .clientError, summary: "Client Error") {
    "Client error received"
}

A default catch all response for anything not otherwise specified, expecting a data response. Generated function returns (Data, HTTPResponse).

Response.defaultData(summary: "Default Response") {
    "This is a default catch-all response."
}