Complete type definitions for OpenAPI 3.0 specification including documents, components, operations, schemas, parameters, and security definitions. These types provide full TypeScript support for working with OpenAPI 3.0 documents with proper typing for all components.
Root document interface and core components for OpenAPI 3.0 specifications.
/**
* Root OpenAPI 3.0 document structure
*/
interface OpenAPI3Document extends Extensions {
/** OpenAPI version string (e.g., "3.0.0") */
openapi: string;
/** API metadata information */
info: Info;
/** Available paths and operations */
paths: Dictionary<PathItem>;
/** External documentation reference */
externalDocs?: ExternalDocumentation;
/** Server definitions */
servers?: Array<Server>;
/** Global security requirements */
security?: Array<SecurityRequirement>;
/** API tags for grouping */
tags?: Array<Tag>;
/** Reusable components */
components?: Components;
}
/**
* Reusable components container
*/
interface Components extends Extensions {
/** Schema definitions */
schemas?: Dictionary<Schema>;
/** Response definitions */
responses?: Dictionary<Response>;
/** Parameter definitions */
parameters?: Dictionary<Parameter>;
/** Example definitions */
examples?: Dictionary<Example>;
/** Request body definitions */
requestBodies?: Dictionary<RequestBody>;
/** Header definitions */
headers?: Dictionary<Header>;
/** Security scheme definitions */
securitySchemes?: Dictionary<SecurityScheme>;
/** Link definitions */
links?: Dictionary<Link>;
/** Callback definitions */
callbacks?: Dictionary<Callback>;
}
/**
* API metadata information
*/
interface Info extends Extensions {
/** API title */
title: string;
/** API description */
description?: string;
/** Terms of service URL */
termsOfService?: string;
/** Contact information */
contact?: Contact;
/** License information */
license?: License;
/** API version */
version: string;
}Path items and HTTP operations for OpenAPI 3.0 documents.
/**
* Path item containing operations and metadata
*/
interface PathItem extends Extensions, Partial<Record<HttpMethod, HttpOperation>> {
/** Reference to another PathItem */
$ref?: string | PathItem;
/** Path summary */
summary?: string;
/** Path description */
description?: string;
/** Path-specific servers */
servers?: Server[];
/** Parameters shared across operations */
parameters?: ParameterReference<Parameter>[];
}
/**
* HTTP operation definition
*/
interface HttpOperation extends Deprecatable, Extensions, Implementation<HttpOperationDetails> {
/** Operation tags for grouping */
tags?: Array<string>;
/** Operation summary */
summary?: string;
/** Operation description */
description?: string;
/** External documentation */
externalDocs?: ExternalDocumentation;
/** Unique operation identifier */
operationId?: string;
/** Operation parameters */
parameters?: ParameterReference<Parameter>[];
/** Request body definition */
requestBody?: Refable<RequestBody>;
/** Response definitions by status code */
responses: Dictionary<Refable<Response>>;
/** Callback definitions */
callbacks?: Dictionary<Refable<Callback>>;
/** Operation-specific security */
security?: Array<SecurityRequirement>;
/** Operation-specific servers */
servers?: Array<Server>;
}
/**
* HTTP methods supported in OpenAPI 3.0
*/
type HttpMethod = "get" | "put" | "post" | "delete" | "options" | "head" | "patch" | "trace";Schema definitions and JSON type system for OpenAPI 3.0.
/**
* JSON Schema definition for OpenAPI 3.0
*/
interface Schema extends Deprecatable, Extensions, Implementation<SchemaDetails> {
/** Schema type */
type?: EnumStr<JsonType>;
/** Schema title */
title?: string;
/** Schema description */
description?: string;
/** Format constraint */
format?: string;
/** Whether null values are allowed */
nullable?: boolean;
/** Read-only property */
readOnly?: boolean;
/** Write-only property */
writeOnly?: boolean;
/** Required property names */
required?: Array<string>;
/** Number constraints */
multipleOf?: number;
maximum?: number;
exclusiveMaximum?: boolean;
minimum?: number;
exclusiveMinimum?: boolean;
/** String constraints */
maxLength?: number;
minLength?: number;
pattern?: string;
/** Array constraints */
maxItems?: number;
minItems?: number;
uniqueItems?: boolean;
/** Object constraints */
maxProperties?: number;
minProperties?: number;
/** Default and example values */
example?: any;
default?: any;
/** Metadata objects */
discriminator?: Discriminator;
externalDocs?: ExternalDocumentation;
xml?: XML;
/** Enumerated values */
enum?: Array<any>;
/** Schema composition */
not?: Refable<Schema>;
allOf?: Array<Refable<Schema>>;
oneOf?: Array<Refable<Schema>>;
anyOf?: Array<Refable<Schema>>;
/** Array items and object properties */
items?: Refable<Schema>;
properties?: Dictionary<PropertyReference<Schema>>;
additionalProperties?: boolean | Refable<Schema>;
}
/**
* JSON data types
*/
enum JsonType {
Array = "array",
Boolean = "boolean",
Integer = "integer",
Number = "number",
Object = "object",
String = "string",
}Parameter definitions for different locations in OpenAPI 3.0.
/**
* Parameter definition
*/
interface Parameter
extends Deprecatable,
Partial<HasSchema>,
Partial<HasContent>,
Partial<HasExample>,
Partial<HasExamples>,
Extensions {
/** Parameter name */
name: string;
/** Parameter location */
in: EnumStr<ParameterLocation>;
/** Parameter description */
description?: string;
/** Whether empty values are allowed */
allowEmptyValue?: boolean;
/** Whether parameter is required */
required?: boolean;
/** Parameter style */
style?: EnumStr<EncodingStyle>;
/** Whether reserved characters are allowed */
allowReserved?: boolean;
}
/**
* Parameter locations
*/
enum ParameterLocation {
Query = "query",
Header = "header",
Cookie = "cookie",
Path = "path",
}
/**
* Parameter encoding styles
*/
enum EncodingStyle {
Matrix = "matrix",
Label = "label",
Simple = "simple",
Form = "form",
SpaceDelimited = "spaceDelimited",
PipeDelimited = "pipeDelimited",
TabDelimited = "tabDelimited",
DeepObject = "deepObject",
}Request body and response definitions for OpenAPI 3.0.
/**
* Request body definition
*/
interface RequestBody extends Extensions {
/** Request body description */
description?: string;
/** Content by media type */
content: Dictionary<MediaType>;
/** Whether request body is required */
required?: boolean;
/** Client flattening extension */
"x-ms-client-flatten"?: boolean;
/** Parameter location extension */
"x-ms-parameter-location"?: string;
}
/**
* Response definition
*/
interface Response extends Extensions {
/** Response description */
description: string;
/** Response headers */
headers?: Dictionary<Refable<Header>>;
/** Response content by media type */
content?: Dictionary<MediaType>;
/** Response links */
links?: Dictionary<Refable<Link>>;
}
/**
* Media type definition
*/
interface MediaType extends Extensions, Partial<HasExample>, Partial<HasExamples> {
/** Content schema */
schema?: Refable<Schema>;
/** Encoding information for multipart/form-data */
encoding?: Dictionary<Encoding>;
}
/**
* Header definition
*/
interface Header
extends Deprecatable,
Extensions,
Partial<HasContent>,
Partial<HasSchema>,
Partial<HasExample>,
Partial<HasExamples> {
/** Header description */
description?: string;
/** Whether header is required */
required?: boolean;
/** Whether empty values are allowed */
allowEmptyValue?: boolean;
/** Whether reserved characters are allowed */
allowReserved?: boolean;
}Security schemes and requirements for OpenAPI 3.0.
/**
* Security requirement mapping
*/
interface SecurityRequirement extends Dictionary<string[]> {}
/**
* Union of all security scheme types
*/
type SecurityScheme =
| APIKeySecurityScheme
| HTTPSecurityScheme
| OAuth2SecurityScheme
| OpenIdConnectSecurityScheme;
/**
* API Key security scheme
*/
interface APIKeySecurityScheme extends Extensions {
type: SecurityType.ApiKey;
/** Parameter name for API key */
name: string;
/** Location of API key */
in: EnumStr<ParameterLocation>;
/** Security scheme description */
description?: string;
}
/**
* HTTP security scheme (Bearer or Basic)
*/
type HTTPSecurityScheme = NonBearerHTTPSecurityScheme | BearerHTTPSecurityScheme;
/**
* Bearer token HTTP security scheme
*/
interface BearerHTTPSecurityScheme extends Extensions {
scheme: Scheme.Bearer;
/** Bearer token format hint */
bearerFormat?: string;
type: SecurityType.Http;
/** Security scheme description */
description?: string;
}
/**
* OAuth2 security scheme
*/
interface OAuth2SecurityScheme extends Extensions {
type: SecurityType.OAuth2;
/** OAuth2 flow definitions */
flows: OAuthFlows;
/** Security scheme description */
description?: string;
}
/**
* Security scheme types
*/
enum SecurityType {
ApiKey = "apiKey",
Http = "http",
OAuth2 = "oauth2",
OpenIDConnect = "openIdConnect",
}Type guards for runtime type checking of OpenAPI 3.0 components.
/**
* Check if parameter has content property
*/
function hasContent<T extends Partial<HasContent>>(parameter: T): parameter is HasContent & T;
/**
* Check if parameter has schema property
*/
function hasSchema<T extends Partial<HasSchema>>(parameter: T): parameter is HasSchema & T;
/**
* Check if parameter has example property
*/
function hasExample<T extends HasExample>(parameter: T): parameter is HasExample & T;
/**
* Check if parameter has examples property
*/
function hasExamples<T extends HasExamples>(parameter: T): parameter is HasExamples & T;
/**
* Check if parameter is a cookie parameter
*/
function isCookieParameter(parameter: Parameter): parameter is InCookie & Parameter;
/**
* Check if parameter is a header parameter
*/
function isHeaderParameter(parameter: Parameter): parameter is InHeader & Parameter;
/**
* Check if parameter is a path parameter
*/
function isPathParameter(parameter: Parameter): parameter is InPath & Parameter;
/**
* Check if parameter is a query parameter
*/
function isQueryParameter(parameter: Parameter): parameter is InQuery & Parameter;Internal helper interfaces that provide support for parameter and property typing.
/**
* Base implementation interface for extensible components
*/
interface Implementation<T> {}
/**
* Base details interface
*/
interface Details {}
/**
* Property reference details with additional metadata
*/
interface PropertyDetails extends Details, Extensions {
/** Property description override */
description?: string;
/** Whether property is read-only */
readOnly?: boolean;
/** Whether property can be null */
nullable?: boolean;
}
/**
* Parameter reference details with additional metadata
*/
interface ParameterDetails extends Details, Extensions {
/** Parameter description override */
description?: string;
}
/**
* Schema implementation details
*/
interface SchemaDetails extends Details {}
/**
* HTTP operation implementation details
*/
interface HttpOperationDetails extends Details {}
/**
* Parameter with schema definition capability
*/
interface HasSchema {
/** Parameter schema */
schema?: Refable<Schema>;
/** Parameter style for serialization */
style?: EnumStr<EncodingStyle>;
/** Whether parameter should explode */
explode?: boolean;
}
/**
* Parameter with content definition capability
*/
interface HasContent {
/** Content by media type */
content: Dictionary<MediaType>;
}
/**
* Component with single example
*/
interface HasExample {
/** Example value */
example?: any;
}
/**
* Component with multiple examples
*/
interface HasExamples {
/** Named examples */
examples?: Dictionary<Refable<Example>>;
}
/**
* Cookie parameter location interface
*/
interface InCookie extends HasSchema, Partial<HasExample>, Partial<HasExamples> {
/** Parameter location */
in: ParameterLocation.Cookie;
}
/**
* Header parameter location interface
*/
interface InHeader extends HasSchema, Partial<HasExample>, Partial<HasExamples> {
/** Parameter location */
in: ParameterLocation.Header;
}
/**
* Path parameter location interface
*/
interface InPath extends HasSchema, Partial<HasExample>, Partial<HasExamples> {
/** Parameter location */
in: ParameterLocation.Path;
}
/**
* Query parameter location interface
*/
interface InQuery extends HasSchema, Partial<HasExample>, Partial<HasExamples> {
/** Parameter location */
in: ParameterLocation.Query;
}
/**
* Utility type for enum string values
*/
type EnumStr<T> = T | string;
/**
* Dictionary type for key-value mappings
*/
type Dictionary<T> = { [key: string]: T };
/**
* Interface for deprecated components
*/
interface Deprecatable {
/** Whether this component is deprecated */
deprecated?: boolean;
}Format definitions for string, integer, and number types.
/**
* String format constraints
*/
enum StringFormat {
None = "",
Char = "char",
Byte = "byte",
Binary = "binary",
Date = "date",
Time = "time",
DateTime = "date-time",
Password = "password",
DateTimeRfc1123 = "date-time-rfc1123",
DateTimeRfc7231 = "date-time-rfc7231",
Duration = "duration",
Uuid = "uuid",
Base64Url = "base64url",
Uri = "uri",
Url = "url",
ArmId = "arm-id",
OData = "odata-query",
Certificate = "certificate",
}
/**
* Integer format constraints
*/
enum IntegerFormat {
None = "",
Int32 = "int32",
Int64 = "int64",
UnixTime = "unixtime",
}
/**
* Number format constraints
*/
enum NumberFormat {
None = "",
Float = "float",
Double = "double",
Decimal = "decimal",
}Working with OpenAPI 3.0 Documents:
import {
OpenAPI3Document,
Schema,
Parameter,
ParameterLocation,
isQueryParameter
} from "@azure-tools/openapi/v3";
const openApiDoc: OpenAPI3Document = {
openapi: "3.0.0",
info: {
title: "User API",
version: "1.0.0"
},
paths: {
"/users": {
get: {
parameters: [
{
name: "limit",
in: "query",
schema: { type: "integer", minimum: 1, maximum: 100 },
description: "Number of users to return"
}
],
responses: {
"200": {
description: "List of users",
content: {
"application/json": {
schema: {
type: "array",
items: { $ref: "#/components/schemas/User" }
}
}
}
}
}
}
}
},
components: {
schemas: {
User: {
type: "object",
required: ["id", "name"],
properties: {
id: { type: "string", format: "uuid" },
name: { type: "string", minLength: 1 },
email: { type: "string", format: "email" },
age: { type: "integer", minimum: 0 }
}
}
}
}
};
// Work with parameters
const getUserOp = openApiDoc.paths["/users"]?.get;
if (getUserOp?.parameters) {
getUserOp.parameters.forEach(param => {
if (isQueryParameter(param)) {
console.log(`Query param: ${param.name}`);
}
});
}Using Type Guards:
import {
Parameter,
hasSchema,
hasContent,
isQueryParameter,
isPathParameter
} from "@azure-tools/openapi/v3";
function processParameter(param: Parameter) {
// Check parameter location
if (isQueryParameter(param)) {
console.log(`Query parameter: ${param.name}`);
if (param.allowReserved) {
console.log("Allows reserved characters");
}
} else if (isPathParameter(param)) {
console.log(`Path parameter: ${param.name} (required)`);
}
// Check parameter definition style
if (hasSchema(param)) {
console.log("Has schema:", param.schema);
} else if (hasContent(param)) {
console.log("Has content:", Object.keys(param.content));
}
}Working with Schemas:
import { Schema, JsonType } from "@azure-tools/openapi/v3";
const userSchema: Schema = {
type: "object",
required: ["id", "name"],
properties: {
id: {
type: "string",
format: "uuid",
description: "Unique user identifier"
},
name: {
type: "string",
minLength: 1,
maxLength: 100
},
preferences: {
type: "object",
additionalProperties: { type: "string" }
},
tags: {
type: "array",
items: { type: "string" },
uniqueItems: true
}
}
};
// Validate schema structure
if (userSchema.type === JsonType.Object && userSchema.properties) {
Object.entries(userSchema.properties).forEach(([prop, schema]) => {
console.log(`Property ${prop}:`, schema);
});
}