tessl/npm-openapi3-ts
TypeScript models and utilities for building OpenAPI 3.x specification documents with fluent DSL builder pattern
—
Pending
Quality
Pending
Does it follow best practices?
Impact
Pending
No eval scenarios have been run
openapi30-types.mddocs/
OpenAPI 3.0 Types
Complete TypeScript interfaces for all OpenAPI 3.0 specification components including schemas, operations, and security definitions.
Capabilities
Core Document Interfaces
Main interfaces for the OpenAPI document structure.
/**
* Root OpenAPI 3.0 document object
*/
interface OpenAPIObject extends ISpecificationExtension {
openapi: string;
info: InfoObject;
servers?: ServerObject[];
paths: PathsObject;
components?: ComponentsObject;
security?: SecurityRequirementObject[];
tags?: TagObject[];
externalDocs?: ExternalDocumentationObject;
}
/**
* API metadata information
*/
interface InfoObject extends ISpecificationExtension {
title: string;
description?: string;
termsOfService?: string;
contact?: ContactObject;
license?: LicenseObject;
version: string;
}
/**
* Contact information for the API
*/
interface ContactObject extends ISpecificationExtension {
name?: string;
url?: string;
email?: string;
}
/**
* License information for the API
*/
interface LicenseObject extends ISpecificationExtension {
name: string;
url?: string;
}Component Container Interface
Interface for reusable OpenAPI components.
/**
* Container for reusable components
*/
interface ComponentsObject extends ISpecificationExtension {
schemas?: { [schema: string]: SchemaObject | ReferenceObject };
responses?: { [response: string]: ResponseObject | ReferenceObject };
parameters?: { [parameter: string]: ParameterObject | ReferenceObject };
examples?: { [example: string]: ExampleObject | ReferenceObject };
requestBodies?: { [request: string]: RequestBodyObject | ReferenceObject };
headers?: { [header: string]: HeaderObject | ReferenceObject };
securitySchemes?: { [securityScheme: string]: SecuritySchemeObject | ReferenceObject };
links?: { [link: string]: LinkObject | ReferenceObject };
callbacks?: { [callback: string]: CallbackObject | ReferenceObject };
}Path and Operation Interfaces
Interfaces for defining API paths and operations.
/**
* Container for API paths (renamed from PathObject for spec consistency)
*/
interface PathsObject extends ISpecificationExtension {
[path: string]: PathItemObject;
}
/**
* @deprecated Use PathsObject instead
*/
type PathObject = PathsObject;
/**
* Single path item with HTTP operations
*/
interface PathItemObject extends ISpecificationExtension {
$ref?: string;
summary?: string;
description?: string;
get?: OperationObject;
put?: OperationObject;
post?: OperationObject;
delete?: OperationObject;
options?: OperationObject;
head?: OperationObject;
patch?: OperationObject;
trace?: OperationObject;
servers?: ServerObject[];
parameters?: (ParameterObject | ReferenceObject)[];
}
/**
* HTTP operation definition
*/
interface OperationObject extends ISpecificationExtension {
tags?: string[];
summary?: string;
description?: string;
externalDocs?: ExternalDocumentationObject;
operationId?: string;
parameters?: (ParameterObject | ReferenceObject)[];
requestBody?: RequestBodyObject | ReferenceObject;
responses: ResponsesObject;
callbacks?: CallbacksObject;
deprecated?: boolean;
security?: SecurityRequirementObject[];
servers?: ServerObject[];
}
/**
* External documentation reference
*/
interface ExternalDocumentationObject extends ISpecificationExtension {
description?: string;
url: string;
}Parameter Interfaces
Interfaces for defining API parameters.
/**
* Parameter location type
*/
type ParameterLocation = 'query' | 'header' | 'path' | 'cookie';
/**
* Parameter serialization style
*/
type ParameterStyle =
| 'matrix'
| 'label'
| 'form'
| 'simple'
| 'spaceDelimited'
| 'pipeDelimited'
| 'deepObject';
/**
* Base parameter properties
*/
interface BaseParameterObject extends ISpecificationExtension {
description?: string;
required?: boolean;
deprecated?: boolean;
allowEmptyValue?: boolean;
style?: ParameterStyle;
explode?: boolean;
allowReserved?: boolean;
schema?: SchemaObject | ReferenceObject;
examples?: { [param: string]: ExampleObject | ReferenceObject };
example?: any;
content?: ContentObject;
}
/**
* Complete parameter definition
*/
interface ParameterObject extends BaseParameterObject {
name: string;
in: ParameterLocation;
}Request and Response Interfaces
Interfaces for request bodies and responses.
/**
* Request body definition
*/
interface RequestBodyObject extends ISpecificationExtension {
description?: string;
content: ContentObject;
required?: boolean;
}
/**
* Content type mappings
*/
interface ContentObject {
[mediatype: string]: MediaTypeObject;
}
/**
* Media type definition with schema and examples
*/
interface MediaTypeObject extends ISpecificationExtension {
schema?: SchemaObject | ReferenceObject;
examples?: ExamplesObject;
example?: any;
encoding?: EncodingObject;
}
/**
* Response definitions container
*/
interface ResponsesObject extends ISpecificationExtension {
default?: ResponseObject | ReferenceObject;
[statuscode: string]: ResponseObject | ReferenceObject | any;
}
/**
* HTTP response definition
*/
interface ResponseObject extends ISpecificationExtension {
description: string;
headers?: HeadersObject;
content?: ContentObject;
links?: LinksObject;
}
/**
* Headers container
*/
interface HeadersObject {
[name: string]: HeaderObject | ReferenceObject;
}
/**
* Header definition (extends BaseParameterObject)
*/
interface HeaderObject extends BaseParameterObject {
$ref?: string;
}Schema Interfaces
JSON Schema interfaces for OpenAPI 3.0.
/**
* JSON Schema types for OpenAPI 3.0
*/
type SchemaObjectType =
| 'integer'
| 'number'
| 'string'
| 'boolean'
| 'object'
| 'null'
| 'array';
/**
* JSON Schema formats
*/
type SchemaObjectFormat =
| 'int32'
| 'int64'
| 'float'
| 'double'
| 'byte'
| 'binary'
| 'date'
| 'date-time'
| 'password'
| string;
/**
* JSON Schema definition for OpenAPI 3.0
*/
interface SchemaObject extends ISpecificationExtension {
nullable?: boolean;
discriminator?: DiscriminatorObject;
readOnly?: boolean;
writeOnly?: boolean;
xml?: XmlObject;
externalDocs?: ExternalDocumentationObject;
example?: any;
examples?: any[];
deprecated?: boolean;
type?: SchemaObjectType | SchemaObjectType[];
format?: SchemaObjectFormat;
allOf?: (SchemaObject | ReferenceObject)[];
oneOf?: (SchemaObject | ReferenceObject)[];
anyOf?: (SchemaObject | ReferenceObject)[];
not?: SchemaObject | ReferenceObject;
items?: SchemaObject | ReferenceObject;
properties?: { [propertyName: string]: SchemaObject | ReferenceObject };
additionalProperties?: SchemaObject | ReferenceObject | boolean;
description?: string;
default?: any;
title?: string;
multipleOf?: number;
maximum?: number;
exclusiveMaximum?: boolean; // Boolean in OpenAPI 3.0
minimum?: number;
exclusiveMinimum?: boolean; // Boolean in OpenAPI 3.0
maxLength?: number;
minLength?: number;
pattern?: string;
maxItems?: number;
minItems?: number;
uniqueItems?: boolean;
maxProperties?: number;
minProperties?: number;
required?: string[];
enum?: any[];
}
/**
* Schemas container
*/
interface SchemasObject {
[schema: string]: SchemaObject;
}
/**
* Polymorphism discriminator
*/
interface DiscriminatorObject {
propertyName: string;
mapping?: { [key: string]: string };
}
/**
* XML serialization metadata
*/
interface XmlObject extends ISpecificationExtension {
name?: string;
namespace?: string;
prefix?: string;
attribute?: boolean;
wrapped?: boolean;
}Reference Interface
Interface for referencing components.
/**
* Reference to another component
*/
interface ReferenceObject {
$ref: string;
}Security Interfaces
Interfaces for API security definitions.
/**
* Security scheme types
*/
type SecuritySchemeType = 'apiKey' | 'http' | 'oauth2' | 'openIdConnect';
/**
* Security scheme definition
*/
interface SecuritySchemeObject extends ISpecificationExtension {
type: SecuritySchemeType;
description?: string;
name?: string; // required only for apiKey
in?: string; // required only for apiKey
scheme?: string; // required only for http
bearerFormat?: string;
flows?: OAuthFlowsObject; // required only for oauth2
openIdConnectUrl?: string; // required only for openIdConnect
}
/**
* OAuth flows container
*/
interface OAuthFlowsObject extends ISpecificationExtension {
implicit?: OAuthFlowObject;
password?: OAuthFlowObject;
clientCredentials?: OAuthFlowObject;
authorizationCode?: OAuthFlowObject;
}
/**
* OAuth flow definition
*/
interface OAuthFlowObject extends ISpecificationExtension {
authorizationUrl?: string;
tokenUrl?: string;
refreshUrl?: string;
scopes: ScopesObject;
}
/**
* OAuth scopes definition
*/
interface ScopesObject extends ISpecificationExtension {
[scope: string]: any;
}
/**
* Security requirement
*/
interface SecurityRequirementObject {
[name: string]: string[];
}Link and Callback Interfaces
Interfaces for response links and callbacks.
/**
* Links container
*/
interface LinksObject {
[name: string]: LinkObject | ReferenceObject;
}
/**
* Link definition for connecting operations
*/
interface LinkObject extends ISpecificationExtension {
operationRef?: string;
operationId?: string;
parameters?: LinkParametersObject;
requestBody?: any | string;
description?: string;
server?: ServerObject;
[property: string]: any;
}
/**
* Link parameters mapping
*/
interface LinkParametersObject {
[name: string]: any | string;
}
/**
* Callbacks container
*/
interface CallbacksObject extends ISpecificationExtension {
[name: string]: CallbackObject | ReferenceObject | any;
}
/**
* Callback definition for asynchronous operations
*/
interface CallbackObject extends ISpecificationExtension {
[name: string]: PathItemObject | any;
}Example and Encoding Interfaces
Interfaces for examples and content encoding.
/**
* Examples container
*/
interface ExamplesObject {
[name: string]: ExampleObject | ReferenceObject;
}
/**
* Example value definition
*/
interface ExampleObject {
summary?: string;
description?: string;
value?: any;
externalValue?: string;
[property: string]: any;
}
/**
* Encoding definitions container
*/
interface EncodingObject extends ISpecificationExtension {
[property: string]: EncodingPropertyObject | any;
}
/**
* Individual encoding property
*/
interface EncodingPropertyObject {
contentType?: string;
headers?: { [key: string]: HeaderObject | ReferenceObject };
style?: string;
explode?: boolean;
allowReserved?: boolean;
[key: string]: any;
}Tag Interface
Interface for API tags.
/**
* Tag metadata for operations
*/
interface TagObject extends ISpecificationExtension {
name: string;
description?: string;
externalDocs?: ExternalDocumentationObject;
[extension: string]: any;
}Type Aliases and Enums
Additional type definitions for parameters, schemas, and security schemes.
/**
* Parameter location options
* @deprecated - Use ParameterLocation type instead
*/
type PathObject = PathsObject;
/**
* The location of a parameter
* Possible values are "query", "header", "path" or "cookie"
*/
type ParameterLocation = 'query' | 'header' | 'path' | 'cookie';
/**
* The style of a parameter
* Describes how the parameter value will be serialized
*/
type ParameterStyle =
| 'matrix'
| 'label'
| 'form'
| 'simple'
| 'spaceDelimited'
| 'pipeDelimited'
| 'deepObject';
/**
* Valid schema types
*/
type SchemaObjectType =
| 'integer'
| 'number'
| 'string'
| 'boolean'
| 'object'
| 'null'
| 'array';
/**
* Valid schema formats
*/
type SchemaObjectFormat =
| 'int32'
| 'int64'
| 'float'
| 'double'
| 'byte'
| 'binary'
| 'date'
| 'date-time'
| 'password'
| string;Utility Functions
Type guards and utility functions for working with OpenAPI types.
/**
* Extract path item from paths object, ignoring extensions
* @param pathsObject - Paths container object
* @param path - Path string to retrieve
* @returns PathItemObject if found, undefined otherwise
*/
function getPath(pathsObject: PathsObject, path: string): PathItemObject | undefined;
/**
* Type guard to check if object is a ReferenceObject
* @param obj - Object to check
* @returns True if object is a ReferenceObject
*/
function isReferenceObject(obj: any): obj is ReferenceObject;
/**
* Type guard to check if schema is a SchemaObject (not a ReferenceObject)
* @param schema - Schema to check
* @returns True if schema is a SchemaObject
*/
function isSchemaObject(schema: SchemaObject | ReferenceObject): schema is SchemaObject;Usage Examples
Complete Type Usage
import { oas30 } from "openapi3-ts";
import { getPath, isReferenceObject, isSchemaObject } from "openapi3-ts/oas30";
// Create typed OpenAPI document
const openApiDoc: oas30.OpenAPIObject = {
openapi: "3.0.3",
info: {
title: "Typed API",
version: "1.0.0"
},
paths: {
"/users": {
get: {
summary: "Get users",
responses: {
"200": {
description: "Success",
content: {
"application/json": {
schema: {
type: "array",
items: { $ref: "#/components/schemas/User" }
}
}
}
}
}
}
}
},
components: {
schemas: {
User: {
type: "object",
required: ["id", "name"],
properties: {
id: { type: "integer", format: "int64" },
name: { type: "string" },
email: { type: "string", format: "email" }
}
}
}
}
};
// Type-safe access with utility functions
const userPath = getPath(openApiDoc.paths, "/users");
if (userPath && userPath.get) {
console.log(userPath.get.summary); // "Get users"
}
// Type guards
const userSchema = openApiDoc.components?.schemas?.User;
if (userSchema && isSchemaObject(userSchema)) {
console.log(userSchema.type); // "object"
console.log(userSchema.required); // ["id", "name"]
}Install with Tessl CLI
npx tessl i tessl/npm-openapi3-ts