Saving progress on types packages

versions/2.0.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
+ * -----
+ *
+ * @key `[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
+}