Parameter DSL type

[tdeleon]

Add a Parameter type for describing valid parameters to a Path or Operation.
See https://spec.openapis.org/oas/v3.2.0.html#parameter-object.

Properties

Name	Type	Description
name	String	Name of the parameter
location	Parameter.Location	Location the parameter is in (path/query/header/cookie)
description	String?	A short description for the parameter, used in generated code comment docs.
required	Bool	Whether the parameter is required or not. In some cases, the parameter is always required.
type	Any.type	The type of the parameter. Must be CustomStringConvertible or RawRepresentable<String>

Location

Parameters can be located in the path, query, header, or cookies, and are indicated with the Parameter.Location enum. When in the path, the name must match the name in the path template (marked within curly braces {}).

Parameter has no public initializers, and instead static factory functions are provided, which accept the relevant parameters for each location type.

Note: Parameters in the request body are defined in the Operation request body (per OpenAPI3 spec).

Path

public static func path<T: CustomStringConvertible>(
        _ name: String,
        ofType type: T.Type = String.self,
        style: Style.Path = .simple,
        description: String? = nil
    ) -> Parameter

Query

public static func query<T: CustomStringConvertible>(
        _ name: String,
        ofType type: T.Type = String.self,
        style: Style.Query = .form,
        description: String? = nil,
        required: Bool = false
    ) -> Parameter

public static func query<T: CustomStringConvertible>(
        _ name: String,
        ofType type: [T].Type,
        style: Style.Query = .form,
        description: String? = nil,
        required: Bool = false
    ) -> Parameter

public static func query<T: RawRepresentable>(
        _ name: String,
        ofType type: T.Type,
        style: Style.Query = .form,
        description: String? = nil,
        required: Bool = false
    ) -> Parameter where T.RawValue == CustomStringConvertible

public static func query(
        _ name: String,
        ofType type: [String: any CustomStringConvertible].Type,
        style: Style.Query = .form,
        description: String? = nil,
        required: Bool = false
    ) -> Parameter

public static func query<T: Encodable>(
        _ name: String,
        ofObjectType type: T.Type,
        style: Style.Query = .form,
        description: String? = nil,
        required: Bool = false
    ) -> Parameter

Header

public static func header<T: LosslessStringConvertible>(
        _ name: String,
        valueType: T.Type = String.self,
        description: String? = nil,
        required: Bool = false
    ) -> Parameter

public static func header<T: LosslessStringConvertible>(
        _ name: String,
        valueType: [T].Type,
        description: String? = nil,
        required: Bool = false
    ) -> Parameter

Cookie

public static func cookie<T: LosslessStringConvertible>(
        _ name: String,
        valueType: T.Type = String.self,
        description: String? = nil,
        required: Bool = false
    ) -> Parameter

public static func cookie<T: LosslessStringConvertible>(
        _ name: String,
        valueType: [T].Type,
        description: String? = nil,
        required: Bool = false
    ) -> Parameter

Examples

Path parameter named "id", of type Int

Parameter.path("id", ofType: Int.self, description: "The user ID")

Required query parameter named "name", of type string

Parameter.query("name", ofType: String.self, description: "The user name", required: true)