openapi-typesafe 0.0.0 → 1.0.0-rc.1

package/src/types/openapi-path-item.ts

@@ -0,0 +1,130 @@
+import type {
+  Extensable,
+  ExternalDocumentationObject,
+  ReferenceObject,
+  ServerObject,
+} from "./openapi-common.js";
+import type { ParameterObject, RequestBodyObject } from "./openapi-request.js";
+import type { ResponsesObject } from "./openapi-response.js";
+import type { SecurityRequirementObject } from "./openapi-security.js";
+
+/**
+ * [4.8.9] Path Item Object
+ * Describes the operations available on a single path. A Path Item MAY be empty, due to ACL
+ * constraints. The path itself is still exposed to the documentation viewer but they will not know
+ * which operations and parameters are available.
+ */
+export interface PathItemObject extends Extensable {
+  /** A definition of a GET operation on this path. */
+  get?: OperationObject | ReferenceObject;
+  /** A definition of a PUT operation on this path. */
+  put?: OperationObject | ReferenceObject;
+  /** A definition of a POST operation on this path. */
+  post?: OperationObject | ReferenceObject;
+  /** A definition of a DELETE operation on this path. */
+  delete?: OperationObject | ReferenceObject;
+  /** A definition of a OPTIONS operation on this path. */
+  options?: OperationObject | ReferenceObject;
+  /** A definition of a HEAD operation on this path. */
+  head?: OperationObject | ReferenceObject;
+  /** A definition of a PATCH operation on this path. */
+  patch?: OperationObject | ReferenceObject;
+  /** A definition of a TRACE operation on this path. */
+  trace?: OperationObject | ReferenceObject;
+  /** A definition of a QUERY operation on this path (OpenAPI 3.2). */
+  query?: OperationObject | ReferenceObject;
+  /**
+   * Operations for other HTTP methods, keyed by the method name exactly as it is sent
+   * (OpenAPI 3.2). The fixed methods above must not appear here.
+   */
+  additionalOperations?: Record<string, OperationObject | ReferenceObject>;
+  /** An alternative server array to service all operations in this path. */
+  servers?: ServerObject[];
+  /**
+   * A list of parameters that are applicable for all the operations described under this path.
+   * These parameters can be overridden at the operation level, but cannot be removed there. The
+   * list MUST NOT include duplicated parameters. A unique parameter is defined by a combination of
+   * a name and location. The list can use the Reference Object to link to parameters that are
+   * defined at the OpenAPI Object’s components/parameters.
+   */
+  parameters?: (ParameterObject | ReferenceObject)[];
+}
+
+/**
+ * [4.8.10] Operation Object
+ * Describes a single API operation on a path.
+ */
+export interface OperationObject extends Extensable {
+  /**
+   * A list of tags for API documentation control. Tags can be used for logical grouping of
+   * operations by resources or any other qualifier.
+   */
+  tags?: string[];
+  /** A short summary of what the operation does. */
+  summary?: string;
+  /**
+   * A verbose explanation of the operation behavior. CommonMark syntax MAY be used for rich text
+   * representation.
+   */
+  description?: string;
+  /** Additional external documentation for this operation. */
+  externalDocs?: ExternalDocumentationObject;
+  /**
+   * Unique string used to identify the operation. The id MUST be unique among all operations
+   * described in the API. The operationId value is case-sensitive. Tools and libraries MAY use the
+   * operationId to uniquely identify an operation, therefore, it is RECOMMENDED to follow common
+   * programming naming conventions.
+   */
+  operationId?: string;
+  /**
+   * A list of parameters that are applicable for this operation. If a parameter is already defined
+   * at the Path Item, the new definition will override it but can never remove it. The list MUST
+   * NOT include duplicated parameters. A unique parameter is defined by a combination of a name and
+   * location. The list can use the Reference Object to link to parameters that are defined at the
+   * OpenAPI Object’s components/parameters.
+   */
+  parameters?: (ParameterObject | ReferenceObject)[];
+  /**
+   * The request body applicable for this operation. The requestBody is fully supported in HTTP
+   * methods where the HTTP 1.1 specification [RFC7231] has explicitly defined semantics for request
+   * bodies. In other cases where the HTTP spec is vague (such as GET, HEAD and DELETE), requestBody
+   * is permitted but does not have well-defined semantics and SHOULD be avoided if possible.
+   */
+  requestBody?: RequestBodyObject | ReferenceObject;
+  /** The list of possible responses as they are returned from executing this operation. */
+  responses?: ResponsesObject;
+  /**
+   * A map of possible out-of band callbacks related to the parent operation. The key is a unique
+   * identifier for the Callback Object. Each value in the map is a Callback Object that describes a
+   * request that may be initiated by the API provider and the expected responses.
+   */
+  callbacks?: Record<string, CallbackObject | ReferenceObject>;
+  /**
+   * Declares this operation to be deprecated. Consumers SHOULD refrain from usage of the declared
+   * operation. Default value is false.
+   */
+  deprecated?: boolean;
+  /**
+   * A declaration of which security mechanisms can be used for this operation. The list of values
+   * includes alternative security requirement objects that can be used. Only one of the security
+   * requirement objects need to be satisfied to authorize a request. To make security optional, an
+   * empty security requirement ({}) can be included in the array. This definition overrides any
+   * declared top-level security. To remove a top-level security declaration, an empty array can be
+   * used.
+   */
+  security?: SecurityRequirementObject[];
+  /**
+   * An alternative server array to service this operation. If an alternative server object is
+   * specified at the Path Item Object or Root level, it will be overridden by this value.
+   */
+  servers?: ServerObject[];
+}
+
+/**
+ * [4.8.18] Callback Object
+ * A map of possible out-of band callbacks related to the parent operation. Each value in the map is
+ * a Path Item Object that describes a set of requests that may be initiated by the API provider and
+ * the expected responses. The key value used to identify the path item object is an expression,
+ * evaluated at runtime, that identifies a URL to use for the callback operation.
+ */
+export type CallbackObject = Record<string, PathItemObject>;

package/src/types/openapi-request.ts

@@ -0,0 +1,209 @@
+import type { Extensable, ReferenceObject } from "./openapi-common.js";
+import type { SchemaObject } from "./openapi-schema.js";
+
+/**
+ * [4.8.12] Parameter Object
+ * Describes a single operation parameter.
+ * A unique parameter is defined by a combination of a name and location.
+ */
+export interface ParameterObject extends Extensable {
+  /**
+   * REQUIRED. The name of the parameter. Parameter names are case sensitive.
+   *
+   * - If `in` is `"path"`, the `name` field MUST correspond to a template expression occurring
+   * within the path field in the Paths Object. See Path Templating for further information.
+   * - If `in` is `"header"` and the `name` field is `"Accept"`, `"Content-Type"` or
+   * `"Authorization"`, the parameter definition SHALL be ignored.
+   * - For all other cases, the `name` corresponds to the parameter name used by the `in` property.
+   */
+  name: string;
+  /**
+   * REQUIRED. The location of the parameter. Possible values are "query", "header", "path",
+   * "cookie", or "querystring" (OpenAPI 3.2: the whole query string, described by `content`).
+   */
+  in: "query" | "header" | "path" | "cookie" | "querystring";
+  /**
+   * A brief description of the parameter. This could contain examples of use. CommonMark syntax MAY
+   * be used for rich text representation.
+   */
+  description?: string;
+  /**
+   * Determines whether this parameter is mandatory. If the parameter location is "path", this
+   * property is REQUIRED and its value MUST be true. Otherwise, the property MAY be included and
+   * its default value is false.
+   */
+  required?: boolean;
+  /**
+   * Specifies that a parameter is deprecated and SHOULD be transitioned out of usage. Default value
+   * is false.
+   */
+  deprecated?: boolean;
+  /**
+   * Sets the ability to pass empty-valued parameters. This is valid only for query parameters and
+   * allows sending a parameter with an empty value. Default value is false. If style is used, and
+   * if behavior is n/a (cannot be serialized), the value of allowEmptyValue SHALL be ignored. Use
+   * of this property is NOT RECOMMENDED, as it is likely to be removed in a later revision.
+   */
+  allowEmptyValue?: boolean;
+  /**
+   * Describes how the parameter value will be serialized depending on the type of the parameter
+   * value. Default values (based on value of in): for query - form; for path - simple; for header -
+   * simple; for cookie - form.
+   */
+  style?: string;
+  /**
+   * When this is true, parameter values of type `array` or `object` generate separate parameters
+   * for each value of the array or key-value pair of the map. For other types of parameters this
+   * property has no effect. When `style` is `form`, the default value is `true`. For all other
+   * styles, the default value is `false`.
+   */
+  explode?: boolean;
+  /**
+   * Determines whether the parameter value SHOULD allow reserved characters, as defined by
+   * [RFC3986] `:/?#[]@!$&'()*+,;=` to be included without percent-encoding. This property only
+   * applies to parameters with an `in` value of `query`. The default value is `false`.
+   */
+  allowReserved?: boolean;
+  /** The schema defining the type used for the parameter. */
+  schema?: SchemaObject;
+  /** Example of the parameter’s potential value. */
+  example?: any;
+  /** Examples of the parameter’s potential value. */
+  examples?: { [name: string]: ExampleObject | ReferenceObject };
+  /** A map containing the representations for the parameter. */
+  content?: { [contentType: string]: MediaTypeObject | ReferenceObject };
+}
+
+/**
+ * [4.8.13] Request Body Object
+ * Describes a single request body.
+ */
+export interface RequestBodyObject extends Extensable {
+  /**
+   * A brief description of the request body. This could contain examples of use. CommonMark syntax
+   * MAY be used for rich text representation.
+   */
+  description?: string;
+  /**
+   * REQUIRED. The content of the request body. The key is a media type or media type range and the
+   * value describes it. For requests that match multiple keys, only the most specific key is
+   * applicable. e.g. text/plain overrides text
+   */
+  content: { [contentType: string]: MediaTypeObject | ReferenceObject };
+  /** Determines if the request body is required in the request. Defaults to false. */
+  required?: boolean;
+}
+
+/**
+ * [4.8.14] Media Type Object
+ */
+export interface MediaTypeObject extends Extensable {
+  /** The schema defining the content of the request, response, or parameter. */
+  schema?: SchemaObject | ReferenceObject;
+  /**
+   * The schema of each item of a sequential media type such as `application/jsonl` or
+   * `text/event-stream` (OpenAPI 3.2).
+   */
+  itemSchema?: SchemaObject | ReferenceObject;
+  /**
+   * Example of the media type. The example object SHOULD be in the correct format as specified by
+   * the media type. The example field is mutually exclusive of the examples field. Furthermore, if
+   * referencing a schema which contains an example, the example value SHALL override the example
+   * provided by the schema.
+   */
+  example?: any;
+  /**
+   * Examples of the media type. Each example object SHOULD match the media type and specified
+   * schema if present. The examples field is mutually exclusive of the example field. Furthermore,
+   * if referencing a schema which contains an example, the examples value SHALL override the
+   * example provided by the schema.
+   */
+  examples?: { [name: string]: ExampleObject | ReferenceObject };
+  /**
+   * A map between a property name and its encoding information. The key, being the property name,
+   * MUST exist in the schema as a property. The encoding object SHALL only apply to requestBody
+   * objects when the media type is multipart or application/x-www-form-urlencoded.
+   */
+  encoding?: { [propertyName: string]: EncodingObject };
+}
+
+/**
+ * [4.8.15] Encoding Object
+ * A single encoding definition applied to a single schema property.
+ */
+export interface EncodingObject extends Extensable {
+  /**
+   * The Content-Type for encoding a specific property. Default value depends on the property type:
+   * for object - application/json; for array – the default is defined based on the inner type; for
+   * all other cases the default is application/octet-stream. The value can be a specific media type
+   * (e.g. application/json), a wildcard media type (e.g. image/*), or a comma-separated list of the
+   * two types.
+   */
+  contentType?: string;
+  /**
+   * A map allowing additional information to be provided as headers, for example
+   * Content-Disposition. Content-Type is described separately and SHALL be ignored in this section.
+   * This property SHALL be ignored if the request body media type is not a multipart.
+   */
+  headers?: { [name: string]: HeaderObject | ReferenceObject };
+  /**
+   * Describes how a specific property value will be serialized depending on its type. See Parameter
+   * Object for details on the style property. The behavior follows the same values as query
+   * parameters, including default values. This property SHALL be ignored if the request body media
+   * type is not application/x-www-form-urlencoded or multipart/form-data. If a value is explicitly
+   * defined, then the value of contentType (implicit or explicit) SHALL be ignored.
+   */
+  style?: string;
+  /**
+   * When this is true, property values of type array or object generate separate parameters for
+   * each value of the array, or key-value-pair of the map. For other types of properties this
+   * property has no effect. When style is form, the default value is true. For all other styles,
+   * the default value is false. This property SHALL be ignored if the request body media type is
+   * not application/x-www-form-urlencoded or multipart/form-data. If a value is explicitly defined,
+   * then the value of contentType (implicit or explicit) SHALL be ignored.
+   */
+  explode?: string;
+  /**
+   * Determines whether the parameter value SHOULD allow reserved characters, as defined by
+   * [RFC3986] :/?#[]@!$&'()*+,;= to be included without percent-encoding. The default value is
+   * false. This property SHALL be ignored if the request body media type is not
+   * application/x-www-form-urlencoded or multipart/form-data. If a value is explicitly defined,
+   * then the value of contentType (implicit or explicit) SHALL be ignored.
+   */
+  allowReserved?: string;
+}
+
+/**
+ * [4.8.19[ Example Object
+ */
+export interface ExampleObject extends Extensable {
+  /** Short description for the example. */
+  summary?: string;
+  /**
+   * Long description for the example. CommonMark syntax MAY be used for rich text representation.
+   */
+  description?: string;
+  /**
+   * Embedded literal example. The value field and externalValue field are mutually exclusive. To
+   * represent examples of media types that cannot naturally represented in JSON or YAML, use a
+   * string value to contain the example, escaping where necessary.
+   */
+  value?: any;
+  /**
+   * A URI that points to the literal example. This provides the capability to reference examples
+   * that cannot easily be included in JSON or YAML documents. The value field and externalValue
+   * field are mutually exclusive. See the rules for resolving Relative References.
+   */
+  externalValue?: string;
+}
+
+/**
+ * [4.8.21] Header Object
+ * The Header Object follows the structure of the Parameter Object with the following changes:
+ *
+ * 1. `name` MUST NOT be specified, it is given in the corresponding `headers` map.
+ * 2. `in` MUST NOT be specified, it is implicitly in `header`.
+ * 3. All traits that are affected by the location MUST be applicable to a location of `heade`r (for
+ * example, `style`).
+ */
+export type HeaderObject = Omit<ParameterObject, "name" | "in">;

package/src/types/openapi-response.ts

@@ -0,0 +1,81 @@
+import type { Extensable, ReferenceObject, ServerObject } from "./openapi-common.js";
+import type { HeaderObject, MediaTypeObject } from "./openapi-request.js";
+
+/**
+ * [4.8.16] Responses Object
+ * A container for the expected responses of an operation. The container maps a HTTP response code
+ * to the expected response.
+ */
+export type ResponsesObject = {
+  [responseCode: string]: ResponseObject | ReferenceObject;
+} & {
+  /**
+   * The documentation of responses other than the ones declared for specific HTTP response codes.
+   * Use this field to cover undeclared responses.
+   */
+  default?: ResponseObject | ReferenceObject;
+};
+
+/**
+ * [4.8.17] Response Object
+ * Describes a single response from an API Operation, including design-time, static links to
+ * operations based on the response.
+ */
+export interface ResponseObject extends Extensable {
+  /**
+   * REQUIRED. A description of the response. CommonMark syntax MAY be used for rich text
+   * representation.
+   */
+  description: string;
+  /**
+   * Maps a header name to its definition. [RFC7230] states header names are case insensitive. If a
+   * response header is defined with the name "Content-Type", it SHALL be ignored.
+   */
+  headers?: { [name: string]: HeaderObject | ReferenceObject };
+  /**
+   * A map containing descriptions of potential response payloads. The key is a media type or media
+   * type range and the value describes it. For responses that match multiple keys, only the most
+   * specific key is applicable. e.g. text/plain overrides text
+   */
+  content?: { [contentType: string]: MediaTypeObject };
+  /**
+   * A map of operations links that can be followed from the response. The key of the map is a short
+   * name for the link, following the naming constraints of the names for Component Objects.
+   */
+  links?: { [name: string]: LinkObject | ReferenceObject };
+}
+
+/**
+ * [4.8.20] Link Object
+ * The Link object represents a possible design-time link for a response. The presence of a link
+ * does not guarantee the caller’s ability to successfully invoke it, rather it provides a known
+ * relationship and traversal mechanism between responses and other operations.
+ */
+export interface LinkObject extends Extensable {
+  /**
+   * A relative or absolute URI reference to an OAS operation. This field is mutually exclusive of
+   * the operationId field, and MUST point to an Operation Object. Relative operationRef values MAY
+   * be used to locate an existing Operation Object in the OpenAPI definition. See the rules for
+   * resolving Relative References.
+   */
+  operationRef?: string;
+  /**
+   * The name of an existing, resolvable OAS operation, as defined with a unique operationId. This
+   * field is mutually exclusive of the operationRef field.
+   */
+  operationId?: string;
+  /**
+   * A map representing parameters to pass to an operation as specified with operationId or
+   * identified via operationRef. The key is the parameter name to be used, whereas the value can be
+   * a constant or an expression to be evaluated and passed to the linked operation. The parameter
+   * name can be qualified using the parameter location [{in}.]{name} for operations that use the
+   * same parameter name in different locations (e.g. path.id).
+   */
+  parameters?: { [name: string]: `$${string}` };
+  /** A literal value or {expression} to use as a request body when calling the target operation. */
+  requestBody?: `$${string}`;
+  /** A description of the link. CommonMark syntax MAY be used for rich text representation. */
+  description?: string;
+  /** A server object to be used by the target operation. */
+  server?: ServerObject;
+}

package/src/types/openapi-schema.ts

@@ -0,0 +1,169 @@
+import type { Extensable, ExternalDocumentationObject, ReferenceObject } from "./openapi-common.js";
+
+/**
+ * [4.8.24] Schema Object
+ * The Schema Object allows the definition of input and output data types. These types can be
+ * objects, but also primitives and arrays. This object is a superset of the JSON Schema
+ * Specification Draft 2020-12.
+ */
+export type SchemaObject = {
+  /**
+   * The Schema Object allows the definition of input and output data types. These types can be
+   * objects, but also primitives and arrays. This object is a superset of the JSON Schema
+   * Specification Draft 2020-12.
+   */
+  discriminator?: DiscriminatorObject;
+  /**
+   * MAY be used only on properties schemas. It has no effect on root schemas. Adds additional
+   * metadata to describe the XML representation of this property.
+   */
+  xml?: XMLObject;
+  /** Additional external documentation for this schema. */
+  externalDocs?: ExternalDocumentationObject;
+  /** @deprecated */
+  example?: any;
+  title?: string;
+  description?: string;
+  $comment?: string;
+  deprecated?: boolean;
+  readOnly?: boolean;
+  writeOnly?: boolean;
+  enum?: unknown[];
+  /**
+   * Use of this keyword is functionally equivalent to an "enum" (Section 6.1.2) with a single
+   * value.
+   */
+  const?: unknown;
+  default?: unknown;
+  format?: string;
+  /** Media type of the string contents (OpenAPI 3.1, JSON Schema 2020-12), e.g. `image/png`. */
+  contentMediaType?: string;
+  /** How the string's contents are encoded (OpenAPI 3.1, JSON Schema 2020-12), e.g. `base64`. */
+  contentEncoding?: string;
+  additionalProperties?: boolean | Record<string, never> | SchemaObject | ReferenceObject;
+  /** @deprecated in 3.1 (still valid for 3.0) */
+  nullable?: boolean;
+  oneOf?: (SchemaObject | ReferenceObject)[];
+  allOf?: (SchemaObject | ReferenceObject)[];
+  anyOf?: (SchemaObject | ReferenceObject)[];
+  required?: string[];
+  [key: `x-${string}`]: any;
+} & (
+  | StringSubtype
+  | NumberSubtype
+  | IntegerSubtype
+  | ArraySubtype
+  | BooleanSubtype
+  | NullSubtype
+  | ObjectSubtype
+  | {
+      type: ("string" | "number" | "integer" | "array" | "boolean" | "null" | "object")[];
+    }
+);
+
+export interface StringSubtype {
+  type: "string" | ["string", "null"];
+  minLength?: number;
+  maxLength?: number;
+  pattern?: string;
+  enum?: (string | ReferenceObject)[];
+}
+
+export interface NumberSubtype {
+  type: "number" | ["number", "null"];
+  minimum?: number;
+  maximum?: number;
+  enum?: (number | ReferenceObject)[];
+}
+
+export interface IntegerSubtype {
+  type: "integer" | ["integer", "null"];
+  minimum?: number;
+  maximum?: number;
+  enum?: (number | ReferenceObject)[];
+}
+
+export interface ArraySubtype {
+  type: "array" | ["array", "null"];
+  prefixItems?: (SchemaObject | ReferenceObject)[];
+  items?: SchemaObject | ReferenceObject | (SchemaObject | ReferenceObject)[];
+  minItems?: number;
+  maxItems?: number;
+  enum?: (SchemaObject | ReferenceObject)[];
+}
+
+export interface BooleanSubtype {
+  type: "boolean" | ["boolean", "null"];
+  enum?: (boolean | ReferenceObject)[];
+}
+
+export interface NullSubtype {
+  type: "null";
+}
+
+export interface ObjectSubtype {
+  type: "object" | ["object", "null"];
+  properties?: { [name: string]: SchemaObject | ReferenceObject };
+  additionalProperties?: boolean | Record<string, never> | SchemaObject | ReferenceObject;
+  patternProperties?: Record<string, SchemaObject | ReferenceObject>;
+  required?: string[];
+  allOf?: (SchemaObject | ReferenceObject)[];
+  anyOf?: (SchemaObject | ReferenceObject)[];
+  enum?: (SchemaObject | ReferenceObject)[];
+  $defs?: $defs;
+}
+
+/**
+ * [4.8.25] Discriminator Object
+ * When request bodies or response payloads may be one of a number of different schemas, a
+ * discriminator object can be used to aid in serialization, deserialization, and validation. The
+ * discriminator is a specific object in a schema which is used to inform the consumer of the
+ * document of an alternative schema based on the value associated with it.
+ */
+export interface DiscriminatorObject {
+  /**
+   * The name of the property in the payload that will hold the discriminator value. Required
+   * before OpenAPI 3.2; typed as required so existing readers keep a `string`.
+   */
+  propertyName: string;
+  /** An object to hold mappings between payload values and schema names or references. */
+  mapping?: Record<string, string>;
+  /** The schema for payloads without the property or with an unmapped value (OpenAPI 3.2). */
+  defaultMapping?: string;
+  /** If this exists, then a discriminator type should be added to objects matching this path */
+  oneOf?: string[];
+}
+
+/**
+ * [4.8.26] XML Object
+ * A metadata object that allows for more fine-tuned XML model definitions. When using arrays, XML
+ * element names are not inferred (for singular/plural forms) and the `name` property SHOULD be used
+ * to add that information. See examples for expected behavior.
+ */
+export interface XMLObject extends Extensable {
+  /**
+   * Replaces the name of the element/attribute used for the described schema property. When defined
+   * within `items`, it will affect the name of the individual XML elements within the list. When
+   * defined alongside `type` being `array` (outside the `items`), it will affect the wrapping
+   * element and only if `wrapped` is `true`. If `wrapped` is `false`, it will be ignored.
+   */
+  name?: string;
+  /** The URI of the namespace definition. This MUST be in the form of an absolute URI. */
+  namespace?: string;
+  /** The prefix to be used for the name. */
+  prefix?: string;
+  /**
+   * Declares whether the property definition translates to an attribute instead of an element.
+   * Default value is `false`.
+   */
+  attribute?: boolean;
+  /**
+   * MAY be used only for an array definition. Signifies whether the array is wrapped (for example,
+   * `<books><book/><book/></books>`) or unwrapped (`<book/><book/>`). Default value is `false`. The
+   * definition takes effect only when defined alongside `type` being `array` (outside the `items`).
+   */
+  wrapped?: boolean;
+}
+
+/** The `$defs` of a Schema Object: named subschemas. */
+export type $defs = Record<string, SchemaObject>;