Add new OpenAPI 2.0 and 3.0 specifications, including comprehensive type definitions and example files. Update .gitignore and bunfig.toml, and remove obsolete MIGRATION.md. Enhance README with additional usage examples and clarify type definitions.

3.1/components.ts

@@ -0,0 +1,143 @@
+import type { Extension } from "./extensions";
+import type {
+	Callback,
+	Example,
+	Header,
+	Link,
+	Parameter,
+	PathItemObject,
+	RequestBody,
+	Response,
+} from "./paths";
+import type { Reference } from "./references";
+import type { Schema } from "./schema";
+import type { SecurityScheme } from "./security";
+
+/**
+ * -----
+ * Components Object
+ * -----
+ *
+ * Holds a set of reusable objects for different aspects of the OAS. All objects defined
+ * within the components object will have no effect on the API unless they are explicitly
+ * referenced from properties outside the components object.
+ *
+ * | Version | Reference |
+ * |---|-----|
+ * | 3.1.1   | {@link https://spec.openapis.org/oas/v3.1.1#components-object | OpenAPI 3.1.1 Components Object} |
+ * | 3.1.0   | {@link https://spec.openapis.org/oas/v3.1.0#components-object | OpenAPI 3.1.0 Components Object} |
+ *
+ * -----
+ * Fields
+ * -----
+ *
+ * @property `schemas` - An object to hold reusable Schema Objects
+ * @property `responses` - An object to hold reusable Response Objects
+ * @property `parameters` - An object to hold reusable Parameter Objects
+ * @property `examples` - An object to hold reusable Example Objects
+ * @property `requestBodies` - An object to hold reusable Request Body Objects
+ * @property `headers` - An object to hold reusable Header Objects
+ * @property `securitySchemes` - An object to hold reusable Security Scheme Objects
+ * @property `links` - An object to hold reusable Link Objects
+ * @property `callbacks` - An object to hold reusable Callback Objects
+ * @property `pathItems` - An object to hold reusable Path Item Objects
+ * @property `x-${string}` - Specification Extensions
+ *
+ * @note
+ * All the fixed fields declared above are objects that MUST use keys that match the regular expression: `^[a-zA-Z0-9\.\-_]+$`.
+ *
+ * -----
+ * Examples
+ * -----
+ *
+ * @example (simple components):
+ * ```ts
+ * const components: Components = {
+ *   schemas: {
+ *     User: {
+ *       type: "object",
+ *       properties: {
+ *         id: { type: "integer", format: "int64" },
+ *         name: { type: "string" }
+ *       }
+ *     }
+ *   },
+ *   responses: {
+ *     NotFound: {
+ *       description: "Resource not found"
+ *     }
+ *   }
+ * };
+ * ```
+ */
+export interface Components extends Extension {
+	/**
+	 * An object to hold reusable Schema Objects.
+	 *
+	 * @example { User: { type: "object", properties: { id: { type: "integer" } } } }
+	 */
+	schemas?: Record<string, Schema | Reference>;
+
+	/**
+	 * An object to hold reusable Response Objects.
+	 *
+	 * @example { NotFound: { description: "Resource not found" } }
+	 */
+	responses?: Record<string, Response | Reference>;
+
+	/**
+	 * An object to hold reusable Parameter Objects.
+	 *
+	 * @example { UserId: { name: "userId", in: "path", required: true, schema: { type: "string" } } }
+	 */
+	parameters?: Record<string, Parameter | Reference>;
+
+	/**
+	 * An object to hold reusable Example Objects.
+	 *
+	 * @example { UserExample: { value: { id: 1, name: "John Doe" } } }
+	 */
+	examples?: Record<string, Example | Reference>;
+
+	/**
+	 * An object to hold reusable Request Body Objects.
+	 *
+	 * @example { UserRequestBody: { description: "User data", content: { "application/json": { schema: { $ref: "#/components/schemas/User" } } } } }
+	 */
+	requestBodies?: Record<string, RequestBody | Reference>;
+
+	/**
+	 * An object to hold reusable Header Objects.
+	 *
+	 * @example { RateLimit: { description: "Rate limit per hour", schema: { type: "integer" } } }
+	 */
+	headers?: Record<string, Header | Reference>;
+
+	/**
+	 * An object to hold reusable Security Scheme Objects.
+	 *
+	 * @example { ApiKeyAuth: { type: "apiKey", in: "header", name: "X-API-KEY" } }
+	 */
+	securitySchemes?: Record<string, SecurityScheme | Reference>;
+
+	/**
+	 * An object to hold reusable Link Objects.
+	 *
+	 * @example { UserOrders: { operationId: "getOrdersByUserId", parameters: { userId: "$response.body#/id" } } }
+	 */
+	links?: Record<string, Link | Reference>;
+
+	/**
+	 * An object to hold reusable Callback Objects.
+	 *
+	 * @example { UserCreatedCallback: { "{$request.body#/callbackUrl}": { post: { requestBody: { description: "User created event" } } } } }
+	 */
+	callbacks?: Record<string, Callback | Reference>;
+
+	/**
+	 * An object to hold reusable Path Item Objects.
+	 *
+	 * @example { UserPath: { get: { summary: "Get user by ID" } } }
+	 */
+	pathItems?: Record<string, PathItemObject | Reference>;
+}