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/externalDocs.ts

@@ -0,0 +1,119 @@
+import type { Extension } from "./extensions";
+
+/**
+ * -----
+ * External Documentation Object
+ * -----
+ *
+ * Allows referencing an external resource for extended documentation.
+ * This object provides a way to link to additional documentation that
+ * supplements the API specification, such as detailed guides, tutorials,
+ * or reference materials.
+ *
+ * External documentation is commonly used to provide:
+ * - Detailed API guides and tutorials
+ * - SDK documentation and examples
+ * - Integration guides and best practices
+ * - Additional reference materials
+ * - Community resources and support
+ *
+ * | Version | Reference |
+ * |---|-----|
+ * | 2.0     | {@link https://swagger.io/specification/v2/#external-documentation-object | Swagger 2.0 External Documentation Object} |
+ *
+ * -----
+ * Fields
+ * -----
+ *
+ * @property `description` - A short description of the target documentation. GFM syntax can be used for rich text representation.
+ * @property `url` - The URL for the target documentation. Value MUST be in the format of a URL. This field is required.
+ *
+ * @note
+ * The `url` field is required and must be a valid URL. The `description` field
+ * is optional but recommended to provide context about the external documentation.
+ *
+ * -----
+ * Examples
+ * -----
+ *
+ * @example (simple external docs):
+ * ```ts
+ * const simpleDocs: ExternalDocumentation = {
+ *   description: "Find more info here",
+ *   url: "https://swagger.io"
+ * };
+ * ```
+ *
+ * @example (detailed external docs):
+ * ```ts
+ * const detailedDocs: ExternalDocumentation = {
+ *   description: "Complete API documentation with examples and tutorials",
+ *   url: "https://docs.example.com/api"
+ * };
+ * ```
+ *
+ * @example (SDK documentation):
+ * ```ts
+ * const sdkDocs: ExternalDocumentation = {
+ *   description: "SDK documentation and code examples",
+ *   url: "https://github.com/example/sdk"
+ * };
+ * ```
+ *
+ * @example (integration guide):
+ * ```ts
+ * const integrationDocs: ExternalDocumentation = {
+ *   description: "Step-by-step integration guide",
+ *   url: "https://example.com/integration-guide"
+ * };
+ * ```
+ *
+ * @example (community resources):
+ * ```ts
+ * const communityDocs: ExternalDocumentation = {
+ *   description: "Community forum and support resources",
+ *   url: "https://community.example.com/api-support"
+ * };
+ * ```
+ *
+ * @example (minimal external docs):
+ * ```ts
+ * const minimalDocs: ExternalDocumentation = {
+ *   url: "https://example.com/docs"
+ * };
+ * ```
+ */
+export interface ExternalDocumentation extends Extension {
+	/**
+	 * A short description of the target documentation. GFM syntax can be used for
+	 * rich text representation.
+	 *
+	 * This description provides context about what the external documentation
+	 * contains and helps developers understand when and why they should
+	 * reference it.
+	 *
+	 * @see {@link https://swagger.io/specification/v2/#external-documentation-object | Swagger 2.0 Specification - description}
+	 *
+	 * @example "Find more info here"
+	 * @example "Complete API documentation with examples and tutorials"
+	 * @example "SDK documentation and code examples"
+	 * @example "Step-by-step integration guide"
+	 */
+	description?: string;
+
+	/**
+	 * The URL for the target documentation. Value MUST be in the format of a URL.
+	 * This field is required.
+	 *
+	 * The URL should point to a valid, accessible resource that provides
+	 * additional documentation about the API or specific aspects of it.
+	 *
+	 * @see {@link https://swagger.io/specification/v2/#external-documentation-object | Swagger 2.0 Specification - url}
+	 *
+	 * @example "https://swagger.io"
+	 * @example "https://docs.example.com/api"
+	 * @example "https://github.com/example/sdk"
+	 * @example "https://example.com/integration-guide"
+	 */
+	url: string;
+}