openapi-typesafe 0.0.0 → 1.0.0-rc.0

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>;

package/src/types/openapi-security.ts

@@ -0,0 +1,116 @@
+import type { Extensable } from "./openapi-common.js";
+import type { ComponentsObject } from "./openapi-document.js";
+
+/**
+ * [4.8.27] Security Scheme Object
+ * Defines a security scheme that can be used by the operations.
+ */
+export type SecuritySchemeObject = {
+  /**
+   * A description for security scheme. CommonMark syntax MAY be used for rich text representation.
+   */
+  description?: string;
+  [key: `x-${string}`]: any;
+} & (
+  | {
+      /** REQUIRED. The type of the security scheme. */
+      type: "apiKey";
+      /** REQUIRED. The name of the header, query or cookie parameter to be used. */
+      name: string;
+      /** REQUIRED. The location of the API key. */
+      in: "query" | "header" | "cookie";
+    }
+  | {
+      /** REQUIRED. The type of the security scheme. */
+      type: "http";
+      /**
+       * REQUIRED. The name of the HTTP Authorization scheme to be used in the Authorization header
+       * as defined in [RFC7235]. The values used SHOULD be registered in the IANA Authentication
+       * Scheme registry.
+       */
+      scheme: string;
+      /**
+       * A hint to the client to identify how the bearer token is formatted. Bearer tokens are
+       * usually generated by an authorization server, so this information is primarily for
+       * documentation purposes.
+       */
+      bearer?: string;
+    }
+  | {
+      /** REQUIRED. The type of the security scheme. */
+      type: "mutualTLS";
+    }
+  | {
+      /** REQUIRED. Tye type of the security scheme. */
+      type: "oauth2";
+      /** REQUIRED. An object containing configuration information for the flow types supported. */
+      flows: OAuthFlowsObject;
+    }
+  | {
+      /** REQUIRED. Tye type of the security scheme. */
+      type: "openIdConnect";
+      /**
+       * REQUIRED. OpenId Connect URL to discover OAuth2 configuration values. This MUST be in the
+       * form of a URL. The OpenID Connect standard requires the use of TLS.
+       */
+      openIdConnectUrl: string;
+    }
+);
+
+/**
+ * [4.8.26] OAuth Flows Object
+ * Allows configuration of the supported OAuth Flows.
+ */
+export interface OAuthFlowsObject extends Extensable {
+  /** Configuration for the OAuth Implicit flow */
+  implicit?: OAuthFlowObject;
+  /** Configuration for the OAuth Resource Owner Password flow */
+  password?: OAuthFlowObject;
+  /**
+   * Configuration for the OAuth Client Credentials flow. Previously called `application` in OpenAPI
+   * 2.0.
+   */
+  clientCredentials?: OAuthFlowObject;
+  /**
+   * Configuration for the OAuth Authorization Code flow. Previously called `accessCode` in OpenAPI
+   * 2.0.
+   */
+  authorizationCode?: OAuthFlowObject;
+}
+
+/**
+ * [4.8.29] OAuth Flow Object
+ * Configuration details for a supported OAuth Flow
+ */
+export interface OAuthFlowObject extends Extensable {
+  /**
+   * REQUIRED. The authorization URL to be used for this flow. This MUST be in the form of a URL.
+   * The OAuth2 standard requires the use of TLS.
+   */
+  authorizationUrl: string;
+  /**
+   * REQUIRED. The token URL to be used for this flow. This MUST be in the form of a URL. The OAuth2
+   * standard requires the use of TLS.
+   */
+  tokenUrl: string;
+  /**
+   * The URL to be used for obtaining refresh tokens. This MUST be in the form of a URL. The OAuth2
+   * standard requires the use of TLS.
+   */
+  refreshUrl: string;
+  /**
+   * REQUIRED. The available scopes for the OAuth2 security scheme. A map between the scope name and
+   * a short description for it. The map MAY be empty.
+   */
+  scopes: { [name: string]: string };
+}
+
+/**
+ * [4.8.30] Security Requirements Object
+ * Lists the required security schemes to execute this operation. The name used for each property
+ * MUST correspond to a security scheme declared in the Security Schemes under the Components
+ * Object.
+ */
+export type SecurityRequirementObject = {
+  [P in keyof ComponentsObject["securitySchemes"]]?: string[];
+};

package/src/types.ts

@@ -0,0 +1,12 @@
+/**
+ * The public types: the OpenAPI 3 document model (`types/openapi-*.ts`) and the generator options
+ * and context (`types/generator-options.ts`). Code imports them from here.
+ */
+export type * from "./types/generator-options.js";
+export type * from "./types/openapi-common.js";
+export type * from "./types/openapi-document.js";
+export type * from "./types/openapi-path-item.js";
+export type * from "./types/openapi-request.js";
+export type * from "./types/openapi-response.js";
+export type * from "./types/openapi-schema.js";
+export type * from "./types/openapi-security.js";