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

@@ -0,0 +1,209 @@
+import type { Components } from "./components";
+import type { Extension } from "./extensions";
+import type { ExternalDocumentation } from "./externalDocs";
+import type { Info } from "./info";
+import type { Paths } from "./paths";
+import type { SecurityRequirement } from "./security";
+import type { Server } from "./servers";
+import type { Tag } from "./tags";
+import type { Webhooks } from "./webhooks";
+
+/**
+ * -----
+ * OpenAPI Specification
+ * -----
+ *
+ * This is the root object of the OpenAPI document. It contains all the information
+ * needed to describe an API, including metadata, servers, paths, components, and more.
+ *
+ * The OpenAPI Specification (OAS) defines a standard, language-agnostic interface
+ * to RESTful APIs which allows both humans and computers to discover and understand
+ * the capabilities of the service without access to source code, documentation, or
+ * through network traffic inspection.
+ *
+ * | Version | Reference |
+ * |---|-----|
+ * | 3.1.1   | {@link https://spec.openapis.org/oas/v3.1.1#openapi-object | OpenAPI 3.1.1 OpenAPI Object} |
+ * | 3.1.0   | {@link https://spec.openapis.org/oas/v3.1.0#openapi-object | OpenAPI 3.1.0 OpenAPI Object} |
+ *
+ * -----
+ * Fields
+ * -----
+ *
+ * @property `openapi` - Required The version number of the OpenAPI Specification
+ * @property `info` - Required Provides metadata about the API
+ * @property `jsonSchemaDialect` - Optional The default value for the $schema keyword within Schema Objects
+ * @property `servers` - Optional An array of Server Objects
+ * @property `paths` - Optional The available paths and operations for the API
+ * @property `webhooks` - Optional The incoming webhooks that MAY be received as part of this API
+ * @property `components` - Optional An element to hold various schemas for the document
+ * @property `security` - Optional A declaration of which security mechanisms can be used across the API
+ * @property `tags` - Optional A list of tags used by the document with additional metadata
+ * @property `externalDocs` - Optional Additional external documentation
+ * @property `x-${string}` - Specification Extensions
+ *
+ * @note
+ * The `openapi` and `info` fields are required.
+ *
+ * -----
+ * Examples
+ * -----
+ *
+ * @example (minimal specification):
+ * ```ts
+ * const spec: Specification = {
+ *   openapi: "3.1.0",
+ *   info: {
+ *     title: "Pet Store API",
+ *     version: "1.0.0"
+ *   }
+ * };
+ * ```
+ *
+ * @example (complete specification):
+ * ```ts
+ * const spec: Specification = {
+ *   openapi: "3.1.0",
+ *   info: {
+ *     title: "Pet Store API",
+ *     summary: "A sample API that uses a petstore as an example",
+ *     description: "This is a sample server Petstore server.",
+ *     termsOfService: "http://example.com/terms/",
+ *     contact: {
+ *       name: "API Support",
+ *       url: "http://www.example.com/support",
+ *       email: "support@example.com"
+ *     },
+ *     license: {
+ *       name: "Apache 2.0",
+ *       url: "https://www.apache.org/licenses/LICENSE-2.0.html"
+ *     },
+ *     version: "1.0.0"
+ *   },
+ *   servers: [
+ *     {
+ *       url: "https://api.example.com/v1",
+ *       description: "The production API server"
+ *     }
+ *   ],
+ *   paths: {
+ *     "/pets": {
+ *       "get": {
+ *         "summary": "List all pets",
+ *         "responses": {
+ *           "200": {
+ *             "description": "A list of pets"
+ *           }
+ *         }
+ *       }
+ *     }
+ *   },
+ *   components: {
+ *     schemas: {
+ *       Pet: {
+ *         type: "object",
+ *         properties: {
+ *           id: { type: "integer", format: "int64" },
+ *           name: { type: "string" }
+ *         }
+ *       }
+ *     }
+ *   },
+ *   tags: [
+ *     {
+ *       name: "pets",
+ *       description: "Pet store operations"
+ *     }
+ *   ]
+ * };
+ * ```
+ */
+export interface Specification extends Extension {
+	/**
+	 * This string MUST be the version number of the OpenAPI Specification that the
+	 * OpenAPI document uses. The `openapi` field SHOULD be used by tooling to interpret
+	 * the OpenAPI document. This is not related to the API `info.version` string.
+	 * This field is required.
+	 *
+	 * @example "3.1.0"
+	 * @example "3.1.1"
+	 */
+	openapi: string;
+
+	/**
+	 * Provides metadata about the API. The metadata MAY be used by tooling as required.
+	 * This field is required.
+	 *
+	 * @example { title: "Pet Store API", version: "1.0.0" }
+	 */
+	info: Info;
+
+	/**
+	 * The default value for the `$schema` keyword within Schema Objects contained
+	 * within this OAS document. This MUST be in the form of a URI.
+	 *
+	 * @example "https://json-schema.org/draft/2020-12/schema"
+	 */
+	jsonSchemaDialect?: string;
+
+	/**
+	 * An array of Server Objects, which provide connectivity information to a target
+	 * server. If the `servers` property is not provided, or is an empty array, the
+	 * default value would be a Server Object with a `url` value of `/`.
+	 *
+	 * @example [{ url: "https://api.example.com/v1", description: "The production API server" }]
+	 */
+	servers?: Server[];
+
+	/**
+	 * The available paths and operations for the API.
+	 *
+	 * @example { "/pets": { "get": { "summary": "List all pets", "responses": { "200": { "description": "A list of pets" } } } } }
+	 */
+	paths?: Paths;
+
+	/**
+	 * The incoming webhooks that MAY be received as part of this API and that the
+	 * API consumer MAY choose to implement. Closely related to the `callbacks` feature,
+	 * this section describes requests initiated other than by an API call, for example
+	 * by an out of band registration.
+	 *
+	 * @example { "newPet": { "post": { "requestBody": { "description": "Information about a new pet" } } } }
+	 */
+	webhooks?: Webhooks;
+
+	/**
+	 * An element to hold various schemas for the document.
+	 *
+	 * @example { schemas: { Pet: { type: "object", properties: { id: { type: "integer" } } } } }
+	 */
+	components?: Components;
+
+	/**
+	 * A declaration of which security mechanisms can be used across the API. The list
+	 * of values includes alternative security requirement objects that can be used.
+	 * Only one of the security requirement objects need to be satisfied to authorize
+	 * a request. Individual operations can override this definition.
+	 *
+	 * @example [{ "api_key": [] }]
+	 */
+	security?: SecurityRequirement[];
+
+	/**
+	 * A list of tags used by the document with additional metadata. The order of the
+	 * tags can be used to reflect on their order by the parsing tools. Not all tags
+	 * that are used by the Operation Object must be declared. The tags that are not
+	 * declared MAY be organized randomly or based on the tools' logic. Each tag name
+	 * in the list MUST be unique.
+	 *
+	 * @example [{ name: "pets", description: "Pet store operations" }]
+	 */
+	tags?: Tag[];
+
+	/**
+	 * Additional external documentation.
+	 *
+	 * @example { description: "Find out more about our API", url: "https://example.com/docs" }
+	 */
+	externalDocs?: ExternalDocumentation;
+}