Complete type definitions for OpenAPI 2.0 (Swagger) specification including documents, operations, parameters, definitions, and responses. These types provide full TypeScript support for working with Swagger 2.0 documents.
Root document interface and metadata for OpenAPI 2.0 specifications.
/**
* Root OpenAPI 2.0 document structure
*/
interface OpenAPI2Document {
/** OpenAPI version, must be "2.0" */
swagger: "2.0";
/** Optional HTTP schemes supported */
schemes?: string[];
/** Host serving the API */
host?: string;
/** Base path for all API endpoints */
basePath?: string;
/** MIME types the API can produce */
produces?: string[];
/** MIME types the API can consume */
consumes?: string[];
/** Available paths and operations */
paths: { [path: string]: OpenAPI2Path };
/** Schema definitions for reuse */
definitions: { [name: string]: OpenAPI2Definition };
}
/**
* Document information metadata
*/
interface OpenAPI2DocumentInfo {
/** Title of the API */
title: string;
/** Description of the API */
description: string;
/** Version of the API */
version: string;
}Path items and HTTP operations for OpenAPI 2.0 documents.
/**
* Path item containing HTTP operations and shared parameters
*/
type OpenAPI2Path = {
[method in HttpMethod]: OpenAPI2Operation;
} & {
/** Parameters shared across all operations */
parameters: any[];
};
/**
* HTTP operation definition
*/
interface OpenAPI2Operation {
/** Unique operation identifier */
operationId: string;
/** Operation description */
description: string;
/** Response definitions by status code */
responses: OpenAPI2OperationResponses;
/** Operation-specific parameters */
parameters?: Refable<OpenAPI2Parameter>[];
/** MIME types this operation produces */
produces?: string[];
/** MIME types this operation consumes */
consumes?: string[];
}
/**
* HTTP methods supported in OpenAPI 2.0
*/
type HttpMethod = "get" | "post" | "patch" | "put" | "delete" | "options" | "head" | "trace" | "x-trace";
/**
* Custom HTTP method for AutoRest
*/
type HttpMethodCustom = "x-trace";Response definitions and headers for OpenAPI 2.0 operations.
/**
* Response definitions keyed by HTTP status code
*/
type OpenAPI2OperationResponses = {
[statusCode: string]: OpenAPI2OperationResponse
};
/**
* Individual response definition
*/
interface OpenAPI2OperationResponse {
/** Response description */
description: string;
/** Response body schema */
schema?: OpenAPI2Definition;
/** Response examples by content type */
examples?: { [exampleName: string]: unknown };
/** Response headers */
headers?: { [headerName: string]: OpenAPI2ResponseHeader };
}
/**
* Response header definition combining reference and header definition
*/
type OpenAPI2ResponseHeader = PathReference & OpenAPI2HeaderDefinition;Parameter definitions for different parameter locations in OpenAPI 2.0.
/**
* Union of all parameter types
*/
type OpenAPI2Parameter =
| OpenAPI2BodyParameter
| OpenAPI2HeaderParameter
| OpenAPI2FormDataParameter
| OpenAPI2QueryParameter
| OpenAPI2PathParameter;
/**
* Base parameter interface with common extensions
*/
interface OpenAPI2ParameterBase {
/** Client-side parameter name override */
"x-ms-client-name"?: string;
/** Parameter location override */
"x-ms-parameter-location"?: string;
}
/**
* Request body parameter
*/
interface OpenAPI2BodyParameter extends OpenAPI2ParameterBase {
/** Parameter name */
name: string;
/** Parameter location */
in: "body";
/** Request body schema */
schema: OpenAPI2Definition;
/** Parameter description */
description?: string;
/** Whether parameter is required */
required?: boolean;
/** Whether empty values are allowed */
allowEmptyValue?: boolean;
/** Example value */
example?: unknown;
/** Whether to flatten client object */
"x-ms-client-flatten"?: boolean;
}
/**
* Header parameter
*/
interface OpenAPI2HeaderParameter extends OpenAPI2HeaderDefinition, OpenAPI2ParameterBase {
/** Parameter name */
name: string;
/** Parameter location */
in: "header";
/** Whether parameter is required */
required?: boolean;
}
/**
* Form data parameter
*/
interface OpenAPI2FormDataParameter extends OpenAPI2ParameterBase {
/** Parameter name */
name: string;
/** Parameter location */
in: "formData";
/** Parameter type */
type: "string" | "number" | "integer" | "boolean" | "array" | "file";
/** Parameter schema */
schema?: OpenAPI2Definition;
/** Whether empty values are allowed */
allowEmptyValue?: boolean;
/** Parameter description */
description?: string;
/** Whether parameter is required */
required?: boolean;
/** Parameter format */
format?: string;
/** Example value */
example?: unknown;
/** Enumerated values */
enum?: string[];
/** Schema composition */
allOf?: OpenAPI2Definition[];
/** Default value */
default?: unknown;
/** Array item definition */
items?: PrimitiveItems;
/** Whether to flatten client object */
"x-ms-client-flatten"?: boolean;
}
/**
* Query parameter
*/
interface OpenAPI2QueryParameter extends OpenAPI2ParameterBase {
/** Parameter name */
name: string;
/** Parameter location */
in: "query";
/** Parameter type */
type: "string" | "number" | "integer" | "boolean" | "array";
/** Whether empty values are allowed */
allowEmptyValue?: boolean;
/** Parameter description */
description?: string;
/** Whether parameter is required */
required?: boolean;
/** Parameter format */
format?: string;
/** Enumerated values */
enum?: string[];
}
/**
* Path parameter
*/
interface OpenAPI2PathParameter extends OpenAPI2ParameterBase {
/** Parameter name */
name: string;
/** Parameter location */
in: "path";
/** Parameter type */
type: "string" | "number" | "integer" | "boolean" | "array";
/** Whether empty values are allowed */
allowEmptyValue?: boolean;
/** Parameter description */
description?: string;
/** Whether parameter is required */
required?: boolean;
/** Parameter format */
format?: string;
/** Enumerated values */
enum?: string[];
}
/**
* Primitive items for array parameters
*/
interface PrimitiveItems extends OpenAPI2ParameterBase {
/** Item type */
type: "string" | "number" | "integer" | "boolean" | "array" | "file";
/** Item format */
format?: string;
/** Nested items for arrays */
items?: PrimitiveItems;
/** Default value */
default?: unknown;
}Schema definitions and type system for OpenAPI 2.0.
/**
* Schema definition for data types
*/
interface OpenAPI2Definition {
/** Allow additional dynamic properties */
[key: string]: unknown;
/** Additional properties definition */
additionalProperties?: OpenAPI2Definition | PathReference | boolean;
/** Schema composition - all of */
allOf?: OpenAPI2Definition[];
/** Schema description */
description?: string;
/** Enumerated values */
enum?: string[];
/** Value format constraint */
format?: string;
/** Array items definition */
items?: OpenAPI2Definition | PathReference;
/** Schema composition - one of */
oneOf?: (OpenAPI2Definition | PathReference)[];
/** Object properties */
properties?: { [index: string]: OpenAPI2Definition | PathReference };
/** Required property names */
required?: string[];
/** Schema title */
title?: string;
/** Schema type */
type?: OpenAPI2Type;
}
/**
* Supported data types in OpenAPI 2.0
*/
type OpenAPI2Type =
| "array"
| "boolean"
| "byte"
| "date"
| "dateTime"
| "double"
| "float"
| "integer"
| "long"
| "number"
| "object"
| "string";Header definitions for responses in OpenAPI 2.0.
/**
* Header definition for responses
*/
interface OpenAPI2HeaderDefinition {
/** Header value type */
type: "string" | "number" | "integer" | "boolean" | "array";
/** Header schema reference */
schema: PathReference & OpenAPI2Definition;
/** Array items definition */
items: any;
/** Collection format for arrays */
collectionFormat: "csv" | "ssv" | "tsv" | "pipes" | "multi";
/** Header description */
description?: string;
/** Header format */
format?: string;
}Working with OpenAPI 2.0 Documents:
import { OpenAPI2Document, OpenAPI2Operation } from "@azure-tools/openapi/v2";
import { dereference, isReference } from "@azure-tools/openapi";
const swaggerDoc: OpenAPI2Document = {
swagger: "2.0",
host: "api.example.com",
basePath: "/v1",
schemes: ["https"],
paths: {
"/users/{id}": {
get: {
operationId: "getUser",
description: "Get user by ID",
parameters: [
{
name: "id",
in: "path",
type: "string",
required: true,
description: "User ID"
}
],
responses: {
"200": {
description: "User found",
schema: { $ref: "#/definitions/User" }
}
}
}
}
},
definitions: {
User: {
type: "object",
properties: {
id: { type: "string" },
name: { type: "string" },
email: { type: "string", format: "email" }
},
required: ["id", "name"]
}
}
};
// Access operation
const getUserOp = swaggerDoc.paths["/users/{id}"].get;
console.log(getUserOp.operationId); // "getUser"
// Resolve schema reference
const responseSchema = getUserOp.responses["200"].schema;
if (responseSchema && isReference(responseSchema)) {
const resolved = dereference(swaggerDoc, responseSchema);
console.log(resolved.instance); // The User definition
}Working with Parameters:
import { OpenAPI2Parameter, OpenAPI2QueryParameter } from "@azure-tools/openapi/v2";
function isQueryParameter(param: OpenAPI2Parameter): param is OpenAPI2QueryParameter {
return param.in === "query";
}
const parameters: OpenAPI2Parameter[] = [
{
name: "filter",
in: "query",
type: "string",
description: "Filter results"
},
{
name: "data",
in: "body",
schema: { type: "object" },
description: "Request payload"
}
];
// Filter query parameters
const queryParams = parameters.filter(isQueryParameter);
queryParams.forEach(param => {
console.log(`Query param: ${param.name}, type: ${param.type}`);
});