oaisp - v1.0.0

oaisp/endpoint

Endpoint declarations: typed values capturing an operation’s method, path, parameters, request body, and responses.

Each declaration fuses a route with the codecs its handler uses, so the emitted document and the runtime contract are read from one place. An Endpoint is built with a method constructor (get, post, …) and refined with the with_* combinators; it is opaque so it can never exist without a method and a path.

Types

Endpoint

opaque </>

A single endpoint declaration.

Opaque: build one with a method constructor and refine it with the with_* combinators. Read its parts back with the accessors (method, path, …).

pub opaque type Endpoint

Method

</>

An HTTP method oaisp can document.

pub type Method {
  Get
  Post
  Put
  Patch
  Delete
}

Constructors 

  • Get
  • Post
  • Put
  • Patch
  • Delete

Param

</>

A documented path or query parameter.

pub type Param {
  Param(name: String, schema: schema.Schema, required: Bool)
}

Constructors

Response

</>

A documented response for a status code. body is None for a response with no body (e.g. a 404).

pub type Response {
  Response(
    status: Int,
    body: option.Option(schema.Schema),
    description: option.Option(String),
  )
}

Constructors

Values

body

</> 
pub fn body(endpoint: Endpoint) -> option.Option(schema.Schema)

The endpoint’s request-body schema, if any.

delete

</> 
pub fn delete(path: String) -> Endpoint

A DELETE endpoint at path.

description

</> 
pub fn description(endpoint: Endpoint) -> option.Option(String)

The endpoint’s description, if set.

get

</> 
pub fn get(path: String) -> Endpoint

A GET endpoint at path.

method

</> 
pub fn method(endpoint: Endpoint) -> Method

The endpoint’s HTTP method.

method_to_string

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

The string used for method in an OpenAPI path item (lower-cased).

operation_id

</> 
pub fn operation_id(endpoint: Endpoint) -> option.Option(String)

The endpoint’s operationId, if set.

patch

</> 
pub fn patch(path: String) -> Endpoint

A PATCH endpoint at path.

path

</> 
pub fn path(endpoint: Endpoint) -> String

The endpoint’s path, including any {param} placeholders.

path_params

</> 
pub fn path_params(endpoint: Endpoint) -> List(Param)

The endpoint’s path parameters, in declaration order.

post

</> 
pub fn post(path: String) -> Endpoint

A POST endpoint at path.

put

</> 
pub fn put(path: String) -> Endpoint

A PUT endpoint at path.

query_params

</> 
pub fn query_params(endpoint: Endpoint) -> List(Param)

The endpoint’s query parameters, in declaration order.

query_record

</> 
pub fn query_record(
  endpoint: Endpoint,
) -> option.Option(schema.Schema)

The record type whose scalar fields are reflected into query parameters, if one was set with with_query_record.

responses

</> 
pub fn responses(endpoint: Endpoint) -> List(Response)

The endpoint’s documented responses, in declaration order.

summary

</> 
pub fn summary(endpoint: Endpoint) -> option.Option(String)

The endpoint’s summary, if set.

tags

</> 
pub fn tags(endpoint: Endpoint) -> List(String)

The endpoint’s tags, in declaration order.

with_body

</> 
pub fn with_body(
  endpoint: Endpoint,
  schema: schema.Schema,
) -> Endpoint

Attach a request-body schema, taken from codec.

with_description

</> 
pub fn with_description(
  endpoint: Endpoint,
  description: String,
) -> Endpoint

Set the operation description (longer prose).

with_empty_response

</> 
pub fn with_empty_response(
  endpoint: Endpoint,
  status: Int,
  description: String,
) -> Endpoint

Document an empty (bodyless) response for status, with a description.

with_operation_id

</> 
pub fn with_operation_id(
  endpoint: Endpoint,
  id: String,
) -> Endpoint

Set the operationId, a unique identifier for the operation.

with_path_param

</> 
pub fn with_path_param(
  endpoint: Endpoint,
  name: String,
  schema: schema.Schema,
) -> Endpoint

Document a path parameter. Path parameters are always required.

with_query_param

</> 
pub fn with_query_param(
  endpoint: Endpoint,
  name: String,
  schema: schema.Schema,
  required: Bool,
) -> Endpoint

Document a query parameter, marking whether it is required.

with_query_record

</> 
pub fn with_query_record(
  endpoint: Endpoint,
  schema: schema.Schema,
) -> Endpoint

Document query parameters by reference to a record type: each of the record’s scalar fields becomes a query parameter (an Option field is optional, the rest required). The type is resolved at merge time from the package interface; fields oaisp can’t express as a scalar query parameter are soundly omitted. Mirrors F#’s addQueryParameters<'T>.

with_response

</> 
pub fn with_response(
  endpoint: Endpoint,
  status: Int,
  schema: schema.Schema,
) -> Endpoint

Document a response with a body schema for status.

with_summary

</> 
pub fn with_summary(
  endpoint: Endpoint,
  summary: String,
) -> Endpoint

Set the operation summary (a short one-line label).

with_tag

</> 
pub fn with_tag(endpoint: Endpoint, tag: String) -> Endpoint

Add a tag, used to group operations in the document.

✨ Search Document