oaspec - v0.14.0

oaspec/openapi/spec

Types

Callback

</>

A callback object: maps URL expressions to PathItems.

pub type Callback(stage) {
  Callback(entries: dict.Dict(String, RefOr(PathItem(stage))))
}

Constructors

Components

</>

Components section containing reusable schemas, parameters, etc.

pub type Components(stage) {
  Components(
    schemas: dict.Dict(String, schema.SchemaRef),
    parameters: dict.Dict(String, RefOr(Parameter(stage))),
    request_bodies: dict.Dict(String, RefOr(RequestBody(stage))),
    responses: dict.Dict(String, RefOr(Response(stage))),
    security_schemes: dict.Dict(String, RefOr(SecurityScheme)),
    path_items: dict.Dict(String, RefOr(PathItem(stage))),
    headers: dict.Dict(String, Header),
    examples: dict.Dict(String, value.JsonValue),
    links: dict.Dict(String, Link),
  )
}

Constructors

Contact

</>

Contact information for the API.

pub type Contact {
  Contact(
    name: option.Option(String),
    url: option.Option(String),
    email: option.Option(String),
  )
}

Constructors

Encoding

</>

Encoding definition for a media type property.

pub type Encoding {
  Encoding(
    content_type: option.Option(String),
    style: option.Option(ParameterStyle),
    explode: option.Option(Bool),
  )
}

Constructors

ExternalDoc

</>

An external documentation reference.

pub type ExternalDoc {
  ExternalDoc(url: String, description: option.Option(String))
}

Constructors

</>

Header definition for responses or components.

pub type Header {
  Header(
    description: option.Option(String),
    required: Bool,
    schema: option.Option(schema.SchemaRef),
  )
}

Constructors

HttpMethod

</>

HTTP method enumeration.

pub type HttpMethod {
  Get
  Post
  Put
  Delete
  Patch
  Head
  Options
  Trace
}

Constructors 

  • Get
  • Post
  • Put
  • Delete
  • Patch
  • Head
  • Options
  • Trace

Info

</>

API metadata.

pub type Info {
  Info(
    title: String,
    description: option.Option(String),
    version: String,
    summary: option.Option(String),
    terms_of_service: option.Option(String),
    contact: option.Option(Contact),
    license: option.Option(License),
  )
}

Constructors

License

</>

License information for the API.

pub type License {
  License(name: String, url: option.Option(String))
}

Constructors

</>

Link definition for responses or components.

pub type Link {
  Link(
    operation_id: option.Option(String),
    description: option.Option(String),
  )
}

Constructors

MediaType

</>

Media type definition.

pub type MediaType {
  MediaType(
    schema: option.Option(schema.SchemaRef),
    example: option.Option(value.JsonValue),
    examples: dict.Dict(String, value.JsonValue),
    encoding: dict.Dict(String, Encoding),
  )
}

Constructors

OAuth2Flow

</>

An OAuth2 flow definition.

pub type OAuth2Flow {
  OAuth2Flow(
    authorization_url: option.Option(String),
    token_url: option.Option(String),
    refresh_url: option.Option(String),
    scopes: dict.Dict(String, String),
  )
}

Constructors

OpenApiSpec

</>

Top-level OpenAPI 3.x specification.

pub type OpenApiSpec(stage) {
  OpenApiSpec(
    openapi: String,
    info: Info,
    paths: dict.Dict(String, RefOr(PathItem(stage))),
    components: option.Option(Components(stage)),
    servers: List(Server),
    security: List(SecurityRequirement),
    webhooks: dict.Dict(String, RefOr(PathItem(stage))),
    tags: List(Tag),
    external_docs: option.Option(ExternalDoc),
    json_schema_dialect: option.Option(String),
  )
}

Constructors

Operation

</>

An API operation (endpoint).

pub type Operation(stage) {
  Operation(
    operation_id: option.Option(String),
    summary: option.Option(String),
    description: option.Option(String),
    tags: List(String),
    parameters: List(RefOr(Parameter(stage))),
    request_body: option.Option(RefOr(RequestBody(stage))),
    responses: dict.Dict(
      http.HttpStatusCode,
      RefOr(Response(stage)),
    ),
    deprecated: Bool,
    security: option.Option(List(SecurityRequirement)),
    callbacks: dict.Dict(String, Callback(stage)),
    servers: List(Server),
    external_docs: option.Option(ExternalDoc),
  )
}

Constructors

Parameter

</>

An API parameter. Stage parameter is phantom.

pub type Parameter(stage) {
  Parameter(
    name: String,
    in_: ParameterIn,
    description: option.Option(String),
    required: Bool,
    payload: ParameterPayload,
    style: option.Option(ParameterStyle),
    explode: option.Option(Bool),
    deprecated: Bool,
    allow_reserved: Bool,
    examples: dict.Dict(String, value.JsonValue),
  )
}

Constructors

ParameterIn

</>

Parameter location.

pub type ParameterIn {
  InPath
  InQuery
  InHeader
  InCookie
}

Constructors 

  • InPath
  • InQuery
  • InHeader
  • InCookie

ParameterPayload

</>

How a parameter carries its type information.

pub type ParameterPayload {
  ParameterSchema(schema.SchemaRef)
  ParameterContent(dict.Dict(String, MediaType))
}

Constructors 

  • ParameterSchema(schema.SchemaRef)

    Parameter defined via a JSON Schema.

  • ParameterContent(dict.Dict(String, MediaType))

    Parameter defined via content media type map (mutually exclusive with schema).

ParameterStyle

</>

Parameter serialization style (OpenAPI 3.x).

pub type ParameterStyle {
  FormStyle
  SimpleStyle
  DeepObjectStyle
  MatrixStyle
  LabelStyle
  SpaceDelimitedStyle
  PipeDelimitedStyle
}

Constructors 

  • FormStyle
  • SimpleStyle
  • DeepObjectStyle
  • MatrixStyle
  • LabelStyle
  • SpaceDelimitedStyle
  • PipeDelimitedStyle

PathItem

</>

A path item containing operations for each HTTP method.

pub type PathItem(stage) {
  PathItem(
    summary: option.Option(String),
    description: option.Option(String),
    get: option.Option(Operation(stage)),
    post: option.Option(Operation(stage)),
    put: option.Option(Operation(stage)),
    delete: option.Option(Operation(stage)),
    patch: option.Option(Operation(stage)),
    head: option.Option(Operation(stage)),
    options: option.Option(Operation(stage)),
    trace: option.Option(Operation(stage)),
    parameters: List(RefOr(Parameter(stage))),
    servers: List(Server),
  )
}

Constructors

RefOr

</>

A value that may be a $ref string or a concrete definition. At Unresolved stage, both Ref and Value may appear. At Resolved stage, only Value is present (enforced by resolve).

pub type RefOr(a) {
  Ref(String)
  Value(a)
}

Constructors 

  • Ref(String)
  • Value(a)

RequestBody

</>

A request body definition. Stage parameter is phantom.

pub type RequestBody(stage) {
  RequestBody(
    description: option.Option(String),
    content: dict.Dict(String, MediaType),
    required: Bool,
  )
}

Constructors

Resolved

</>

Phantom type: spec has been through the resolve phase. All RefOr values are guaranteed to be Value, not Ref.

pub type Resolved {
  Resolved
}

Constructors 

  • Resolved

Response

</>

A response definition. Stage parameter is phantom.

pub type Response(stage) {
  Response(
    description: option.Option(String),
    content: dict.Dict(String, MediaType),
    headers: dict.Dict(String, Header),
    links: dict.Dict(String, Link),
  )
}

Constructors

SecurityRequirement

</>

A security requirement.

pub type SecurityRequirement {
  SecurityRequirement(schemes: List(SecuritySchemeRef))
}

Constructors

SecurityScheme

</>

Security scheme definition.

pub type SecurityScheme {
  ApiKeyScheme(name: String, in_: SecuritySchemeIn)
  HttpScheme(
    scheme: String,
    bearer_format: option.Option(String),
  )
  OAuth2Scheme(
    description: option.Option(String),
    flows: dict.Dict(String, OAuth2Flow),
  )
  OpenIdConnectScheme(
    open_id_connect_url: String,
    description: option.Option(String),
  )
  UnsupportedScheme(scheme_type: String)
}

Constructors 

  • ApiKeyScheme(name: String, in_: SecuritySchemeIn)
  • HttpScheme(scheme: String, bearer_format: option.Option(String))
  • OAuth2Scheme(
  description: option.Option(String),
  flows: dict.Dict(String, OAuth2Flow),
)
  • OpenIdConnectScheme(
  open_id_connect_url: String,
  description: option.Option(String),
)
  • UnsupportedScheme(scheme_type: String)

    Parsed but unsupported scheme type (e.g. mutualTLS). Preserved losslessly; capability_check will reject it.

SecuritySchemeIn

</>

Location for apiKey security scheme.

pub type SecuritySchemeIn {
  SchemeInHeader
  SchemeInQuery
  SchemeInCookie
}

Constructors 

  • SchemeInHeader
  • SchemeInQuery
  • SchemeInCookie

SecuritySchemeRef

</>

A single scheme reference within a security requirement (AND element).

pub type SecuritySchemeRef {
  SecuritySchemeRef(scheme_name: String, scopes: List(String))
}

Constructors 

  • SecuritySchemeRef(scheme_name: String, scopes: List(String))

Server

</>

Server object.

pub type Server {
  Server(
    url: String,
    description: option.Option(String),
    variables: dict.Dict(String, ServerVariable),
  )
}

Constructors

ServerVariable

</>

A server variable for server URL template substitution.

pub type ServerVariable {
  ServerVariable(
    default: String,
    enum_values: List(String),
    description: option.Option(String),
  )
}

Constructors 

  • ServerVariable(
  default: String,
  enum_values: List(String),
  description: option.Option(String),
)

Tag

</>

A tag for API documentation control.

pub type Tag {
  Tag(
    name: String,
    description: option.Option(String),
    external_docs: option.Option(ExternalDoc),
  )
}

Constructors

Unresolved

</>

Phantom type: spec has not yet been through the resolve phase. RefOr values may still contain Ref(String).

pub type Unresolved {
  Unresolved
}

Constructors 

  • Unresolved

Values

method_to_lower

</> 
pub fn method_to_lower(method: HttpMethod) -> String

Convert HTTP method to lowercase string.

method_to_string

</> 
pub fn method_to_string(method: HttpMethod) -> String

Convert HTTP method to string.

parameter_schema

</> 
pub fn parameter_schema(
  param: Parameter(stage),
) -> option.Option(schema.SchemaRef)

Extract the schema from a parameter’s payload, if it uses schema encoding.

unwrap_ref

</> 
pub fn unwrap_ref(ref_or: RefOr(a)) -> a

Unwrap a RefOr assuming it has been resolved. Panics on Ref.

✨ Search Document