OpenAPI v3.1

.gitignore

@@ -1,3 +1,4 @@
+lib/
 node_modules/
 
 package-lock.json

package.json

@@ -5,13 +5,19 @@
   "main": "./lib/index.js",
   "typings": "./lib/index.d.ts",
   "scripts": {
-    "test": "echo \"Error: no test specified\" && exit 1"
+    "build": "rimraf lib && tsc"
   },
   "keywords": [],
   "author": "",
   "license": "ISC",
   "devDependencies": {
     "prettier": "^3.2.5",
+    "rimraf": "^5.0.5",
     "typescript": "^5.4.3"
-  }
+  },
+  "files": [
+    "lib",
+    "src",
+    "README.md"
+  ]
 }

src/OpenApiV3.ts

@@ -1,26 +1,27 @@
 export namespace OpenApiV3 {
+  export type Method =
+    | "get"
+    | "post"
+    | "put"
+    | "delete"
+    | "options"
+    | "head"
+    | "patch"
+    | "trace";
+
+  /* -----------------------------------------------------------
+    DOCUMENTS
+  ----------------------------------------------------------- */
   export interface IDocument {
     openapi: `3.0.${number}`;
-    servers?: IDocument.IServer[];
-    info: IDocument.IInfo;
+    servers?: IServer[];
+    info?: IDocument.IInfo;
     components?: IComponents;
-    paths: Record<string, Record<string, IRoute>>;
+    paths?: Record<string, IPathItem>;
     security?: Record<string, string[]>[];
     tags?: IDocument.ITag[];
   }
   export namespace IDocument {
-    export interface IServer {
-      /** @format uri */ url: string;
-      description?: string;
-      variables?: Record<string, IServer.IVariable>;
-    }
-    export namespace IServer {
-      export interface IVariable {
-        default: string;
-        enum?: string[];
-        description?: string;
-      }
-    }
     export interface IInfo {
       title: string;
       description?: string;
@@ -44,26 +45,55 @@ export namespace OpenApiV3 {
     }
   }
 
-  export interface IRoute {
+  export interface IServer {
+    /** @format uri */ url: string;
+    description?: string;
+    variables?: Record<string, IServer.IVariable>;
+  }
+  export namespace IServer {
+    export interface IVariable {
+      default: string;
+      enum?: string[];
+      description?: string;
+    }
+  }
+
+  /* -----------------------------------------------------------
+    PATH ITEMS
+  ----------------------------------------------------------- */
+  export type IPathItem = {
+    parameters?: Array<
+      | IOperation.IParameter
+      | IJsonSchema.IReference<`#/components/headers/${string}`>
+      | IJsonSchema.IReference<`#/components/parameters/${string}`>
+    >;
+    servers?: IServer[];
+    summary?: string;
+    description?: string;
+  } & Partial<Record<Method, IOperation | undefined>>;
+
+  export interface IOperation {
+    operationId?: string;
     parameters?: Array<
-      | IRoute.IParameter
+      | IOperation.IParameter
       | IJsonSchema.IReference<`#/components/headers/${string}`>
       | IJsonSchema.IReference<`#/components/parameters/${string}`>
     >;
     requestBody?:
-      | IRoute.IRequestBody
+      | IOperation.IRequestBody
       | IJsonSchema.IReference<`#/components/requestBodies/${string}`>;
     responses?: Record<
       string,
-      | IRoute.IResponse
+      | IOperation.IResponse
       | IJsonSchema.IReference<`#/components/responses/${string}`>
     >;
+    servers?: IServer[];
     summary?: string;
     description?: string;
     security?: Record<string, string[]>;
     tags?: string[];
   }
-  export namespace IRoute {
+  export namespace IOperation {
     export interface IParameter {
       name?: string;
       in: "path" | "query" | "header" | "cookie";
@@ -78,21 +108,30 @@ export namespace OpenApiV3 {
     }
     export interface IResponse {
       content?: Record<string, IMediaType>;
+      headers?: Record<
+        string,
+        | IOperation.IParameter
+        | IJsonSchema.IReference<`#/components/headers/${string}`>
+      >;
       description?: string;
     }
     export interface IMediaType {
       schema: IJsonSchema;
     }
   }
 
+  /* -----------------------------------------------------------
+    SCHEMA DEFINITIONS
+  ----------------------------------------------------------- */
   export interface IComponents {
     schemas?: Record<string, IJsonSchema>;
-    responses?: Record<string, IRoute.IResponse>;
-    parameters?: Record<string, IRoute.IParameter>;
-    requestBodies?: Record<string, IRoute.IRequestBody>;
+    responses?: Record<string, IOperation.IResponse>;
+    parameters?: Record<string, IOperation.IParameter>;
+    requestBodies?: Record<string, IOperation.IRequestBody>;
     securitySchemes?: Record<string, ISecurityScheme>;
-    headers?: Record<string, IRoute.IParameter>;
+    headers?: Record<string, IOperation.IParameter>;
   }
+
   export type IJsonSchema =
     | IJsonSchema.IBoolean
     | IJsonSchema.IInteger
@@ -130,7 +169,6 @@ export namespace OpenApiV3 {
       multipleOf?: number;
     }
     export interface IString extends __ISignificant<"string"> {
-      contentMediaType?: string;
       default?: string;
       enum?: string[];
       format?:
@@ -173,6 +211,8 @@ export namespace OpenApiV3 {
       properties: Record<string, IJsonSchema>;
       required?: string[];
       additionalProperties?: boolean | IJsonSchema;
+      maxProperties?: number;
+      minProperties?: number;
     }
     export interface IReference<Key = string> extends __IAttribute {
       $ref: Key;
@@ -204,6 +244,7 @@ export namespace OpenApiV3 {
       deprecated?: boolean;
     }
   }
+
   export type ISecurityScheme =
     | ISecurityScheme.IApiKey
     | ISecurityScheme.IHttpBasic