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.

2.0/example.ts

@@ -0,0 +1,75 @@
+import type { Extension } from "./extensions";
+
+/**
+ * -----
+ * Example Object
+ * -----
+ *
+ * Allows sharing examples for operation responses. Examples provide concrete
+ * instances of what the API response will look like, making it easier for
+ * developers to understand the expected data structure and format.
+ *
+ * Examples are commonly used by documentation generators and API testing tools
+ * to provide realistic sample data that developers can use as a reference
+ * when implementing client applications.
+ *
+ * | Version | Reference |
+ * |---|-----|
+ * | 2.0     | {@link https://swagger.io/specification/v2/#example-object | Swagger 2.0 Example Object} |
+ *
+ * -----
+ * Fields
+ * -----
+ *
+ * @property `[mimeType]` - The name of the property MUST be one of the Operation produces values (either implicit or inherited). The value SHOULD be an example of what such a response would look like.
+ *
+ * @note
+ * The property names correspond to MIME types that the operation can produce.
+ *
+ * -----
+ * Examples
+ * -----
+ *
+ * @example (JSON response example):
+ * ```ts
+ * const example: Example = {
+ *   "application/json": {
+ *     "name": "Puma",
+ *     "type": "Dog",
+ *     "color": "Black",
+ *     "gender": "Female",
+ *     "breed": "Mixed"
+ *   }
+ * };
+ * ```
+ *
+ * @example (XML response example):
+ * ```ts
+ * const example: Example = {
+ *   "application/xml": "<pet><name>Puma</name><type>Dog</type></pet>"
+ * };
+ * ```
+ *
+ * @example (multiple content types):
+ * ```ts
+ * const example: Example = {
+ *   "application/json": { "id": 1, "name": "John" },
+ *   "application/xml": "<user><id>1</id><name>John</name></user>"
+ * };
+ * ```
+ */
+export interface Example extends Extension {
+	/**
+	 * The name of the property MUST be one of the Operation produces values
+	 * (either implicit or inherited). The value SHOULD be an example of what
+	 * such a response would look like.
+	 *
+	 * The property name corresponds to a MIME type that the operation can produce.
+	 * The value should be a realistic example of the response data in that format.
+	 *
+	 * @example { "application/json": { name: "Puma", type: "Dog" } }
+	 * @example { "application/xml": "<pet><name>Puma</name></pet>" }
+	 * @example { "text/plain": "Success" }
+	 */
+	[mimeType: string]: unknown;
+}