@zenstackhq/openapi 1.0.0-alpha.98 → 1.0.0-beta.1

package/generator-base.d.ts

@@ -0,0 +1,65 @@
+import { DMMF } from '@prisma/generator-helper';
+import { PluginOptions } from '@zenstackhq/sdk';
+import { Model } from '@zenstackhq/sdk/ast';
+import type { OpenAPIV3_1 as OAPI } from 'openapi-types';
+export declare abstract class OpenAPIGeneratorBase {
+    protected model: Model;
+    protected options: PluginOptions;
+    protected dmmf: DMMF.Document;
+    constructor(model: Model, options: PluginOptions, dmmf: DMMF.Document);
+    abstract generate(): string[];
+    protected get includedModels(): import("@zenstackhq/sdk/ast").DataModel[];
+    protected wrapArray(schema: OAPI.ReferenceObject | OAPI.SchemaObject, isArray: boolean): OAPI.ReferenceObject | OAPI.SchemaObject;
+    protected array(itemType: OAPI.SchemaObject | OAPI.ReferenceObject): {
+        readonly type: "array";
+        readonly items: OAPI.ReferenceObject | OAPI.SchemaObject;
+    };
+    protected oneOf(...schemas: (OAPI.SchemaObject | OAPI.ReferenceObject)[]): {
+        oneOf: (OAPI.ReferenceObject | OAPI.SchemaObject)[];
+    };
+    protected allOf(...schemas: (OAPI.SchemaObject | OAPI.ReferenceObject)[]): {
+        allOf: (OAPI.ReferenceObject | OAPI.SchemaObject)[];
+    };
+    protected getOption<T = string>(name: string): T | undefined;
+    protected getOption<T = string, D extends T = T>(name: string, defaultValue: D): T;
+    protected generateSecuritySchemes(): Record<string, {
+        type: "http";
+        scheme: "basic";
+    } | {
+        bearerFormat?: string | undefined;
+        type: "http";
+        scheme: "bearer";
+    } | {
+        type: "apiKey";
+        in: "header" | "query" | "cookie";
+        name: string;
+    } | {
+        type: "oauth2";
+        description: string;
+        flows: {
+            authorizationCode: {
+                authorizationUrl: string;
+                tokenUrl: string;
+                refreshUrl: string;
+                scopes: Record<string, string>;
+            };
+            implicit: {
+                authorizationUrl: string;
+                refreshUrl: string;
+                scopes: Record<string, string>;
+            };
+            password: {
+                tokenUrl: string;
+                refreshUrl: string;
+                scopes: Record<string, string>;
+            };
+            clientCredentials: {
+                tokenUrl: string;
+                refreshUrl: string;
+                scopes: Record<string, string>;
+            };
+        };
+    }> | undefined;
+    protected pruneComponents(paths: OAPI.PathsObject, components: OAPI.ComponentsObject): void;
+    private collectUsedComponents;
+}

package/generator-base.js

@@ -0,0 +1,103 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.OpenAPIGeneratorBase = void 0;
+const sdk_1 = require("@zenstackhq/sdk");
+const zod_validation_error_1 = require("zod-validation-error");
+const schema_1 = require("./schema");
+class OpenAPIGeneratorBase {
+    constructor(model, options, dmmf) {
+        this.model = model;
+        this.options = options;
+        this.dmmf = dmmf;
+    }
+    get includedModels() {
+        return (0, sdk_1.getDataModels)(this.model).filter((d) => !(0, sdk_1.hasAttribute)(d, '@@openapi.ignore'));
+    }
+    wrapArray(schema, isArray) {
+        if (isArray) {
+            return { type: 'array', items: schema };
+        }
+        else {
+            return schema;
+        }
+    }
+    array(itemType) {
+        return { type: 'array', items: itemType };
+    }
+    oneOf(...schemas) {
+        return { oneOf: schemas };
+    }
+    allOf(...schemas) {
+        return { allOf: schemas };
+    }
+    getOption(name, defaultValue) {
+        const value = this.options[name];
+        // eslint-disable-next-line @typescript-eslint/ban-ts-comment
+        // @ts-expect-error
+        return value === undefined ? defaultValue : value;
+    }
+    generateSecuritySchemes() {
+        const securitySchemes = this.getOption('securitySchemes');
+        if (securitySchemes) {
+            const parsed = schema_1.SecuritySchemesSchema.safeParse(securitySchemes);
+            if (!parsed.success) {
+                throw new sdk_1.PluginError(this.options.name, `"securitySchemes" option is invalid: ${(0, zod_validation_error_1.fromZodError)(parsed.error)}`);
+            }
+            return parsed.data;
+        }
+        return undefined;
+    }
+    pruneComponents(paths, components) {
+        const schemas = components.schemas;
+        if (schemas) {
+            const roots = new Set();
+            for (const path of Object.values(paths)) {
+                this.collectUsedComponents(path, roots);
+            }
+            // build a transitive closure for all reachable schemas from roots
+            const allUsed = new Set(roots);
+            let todo = [...allUsed];
+            while (todo.length > 0) {
+                const curr = new Set(allUsed);
+                Object.entries(schemas)
+                    .filter(([key]) => todo.includes(key))
+                    .forEach(([, value]) => {
+                    this.collectUsedComponents(value, allUsed);
+                });
+                todo = [...allUsed].filter((e) => !curr.has(e));
+            }
+            // prune unused schemas
+            Object.keys(schemas).forEach((key) => {
+                if (!allUsed.has(key)) {
+                    delete schemas[key];
+                }
+            });
+        }
+    }
+    collectUsedComponents(value, allUsed) {
+        if (!value) {
+            return;
+        }
+        if (Array.isArray(value)) {
+            value.forEach((item) => {
+                this.collectUsedComponents(item, allUsed);
+            });
+        }
+        else if (typeof value === 'object') {
+            Object.entries(value).forEach(([subKey, subValue]) => {
+                if (subKey === '$ref') {
+                    const ref = subValue;
+                    const name = ref.split('/').pop();
+                    if (name && !allUsed.has(name)) {
+                        allUsed.add(name);
+                    }
+                }
+                else {
+                    this.collectUsedComponents(subValue, allUsed);
+                }
+            });
+        }
+    }
+}
+exports.OpenAPIGeneratorBase = OpenAPIGeneratorBase;
+//# sourceMappingURL=generator-base.js.map

package/generator-base.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"generator-base.js","sourceRoot":"","sources":["../src/generator-base.ts"],"names":[],"mappings":"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"}

package/index.js

@@ -10,11 +10,21 @@ var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, ge
 };
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.name = void 0;
-const generator_1 = require("./generator");
+const sdk_1 = require("@zenstackhq/sdk");
+const rest_generator_1 = require("./rest-generator");
+const rpc_generator_1 = require("./rpc-generator");
 exports.name = 'OpenAPI';
 function run(model, options, dmmf) {
     return __awaiter(this, void 0, void 0, function* () {
-        return new generator_1.OpenAPIGenerator(model, options, dmmf).generate();
+        const flavor = options.flavor ? options.flavor : 'rpc';
+        switch (flavor) {
+            case 'rest':
+                return new rest_generator_1.RESTfulOpenAPIGenerator(model, options, dmmf).generate();
+            case 'rpc':
+                return new rpc_generator_1.RPCOpenAPIGenerator(model, options, dmmf).generate();
+            default:
+                throw new sdk_1.PluginError(exports.name, `Unknown flavor: ${flavor}`);
+        }
     });
 }
 exports.default = run;

package/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";;;;;;;;;;;;AAGA,2CAA+C;AAElC,QAAA,IAAI,GAAG,SAAS,CAAC;AAE9B,SAA8B,GAAG,CAAC,KAAY,EAAE,OAAsB,EAAE,IAAmB;;QACvF,OAAO,IAAI,4BAAgB,CAAC,KAAK,EAAE,OAAO,EAAE,IAAI,CAAC,CAAC,QAAQ,EAAE,CAAC;IACjE,CAAC;CAAA;AAFD,sBAEC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";;;;;;;;;;;;AACA,yCAA6D;AAE7D,qDAA2D;AAC3D,mDAAsD;AAEzC,QAAA,IAAI,GAAG,SAAS,CAAC;AAE9B,SAA8B,GAAG,CAAC,KAAY,EAAE,OAAsB,EAAE,IAAmB;;QACvF,MAAM,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC,CAAE,OAAO,CAAC,MAAiB,CAAC,CAAC,CAAC,KAAK,CAAC;QAEnE,QAAQ,MAAM,EAAE;YACZ,KAAK,MAAM;gBACP,OAAO,IAAI,wCAAuB,CAAC,KAAK,EAAE,OAAO,EAAE,IAAI,CAAC,CAAC,QAAQ,EAAE,CAAC;YACxE,KAAK,KAAK;gBACN,OAAO,IAAI,mCAAmB,CAAC,KAAK,EAAE,OAAO,EAAE,IAAI,CAAC,CAAC,QAAQ,EAAE,CAAC;YACpE;gBACI,MAAM,IAAI,iBAAW,CAAC,YAAI,EAAE,mBAAmB,MAAM,EAAE,CAAC,CAAC;SAChE;IACL,CAAC;CAAA;AAXD,sBAWC"}

package/meta.d.ts

@@ -1,17 +1,26 @@
 import { DataModel } from '@zenstackhq/sdk/ast';
+/**
+ * Metadata for a resource, expressed by @@openapi.meta attribute.
+ */
+export type ModelMeta = {
+    tagDescription?: string;
+    security?: Array<Record<string, string[]>>;
+};
 /**
  * Metadata for a resource operation, expressed by @@openapi.meta attribute.
  */
 export type OperationMeta = {
-    ignore: boolean;
-    method: string;
-    path: string;
+    ignore?: boolean;
+    method?: string;
+    path?: string;
     summary?: string;
     description?: string;
     tags?: string[];
+    deprecated?: boolean;
+    security?: Array<Record<string, string[]>>;
 };
 /**
  * Metadata for a resource, expressed by @@openapi.meta attribute.
  */
-export type ResourceMeta = Record<string, OperationMeta>;
+export type ResourceMeta = ModelMeta & Record<string, OperationMeta>;
 export declare function getModelResourceMeta(model: DataModel): ResourceMeta | undefined;

package/meta.js.map

@@ -1 +1 @@
-{"version":3,"file":"meta.js","sourceRoot":"","sources":["../src/meta.ts"],"names":[],"mappings":";;;AAAA,yCAAmD;AAoBnD,SAAgB,oBAAoB,CAAC,KAAgB;;IACjD,OAAO,IAAA,sBAAgB,EACnB,MAAA,KAAK,CAAC,UAAU,CAAC,IAAI,CAAC,CAAC,IAAI,EAAE,EAAE,WAAC,OAAA,CAAA,MAAA,IAAI,CAAC,IAAI,CAAC,GAAG,0CAAE,IAAI,MAAK,gBAAgB,CAAA,EAAA,CAAC,0CAAE,IAAI,CAAC,CAAC,EAAE,KAAK,CAC3F,CAAC;AACN,CAAC;AAJD,oDAIC"}
+{"version":3,"file":"meta.js","sourceRoot":"","sources":["../src/meta.ts"],"names":[],"mappings":";;;AAAA,yCAAmD;AA8BnD,SAAgB,oBAAoB,CAAC,KAAgB;;IACjD,OAAO,IAAA,sBAAgB,EACnB,MAAA,KAAK,CAAC,UAAU,CAAC,IAAI,CAAC,CAAC,IAAI,EAAE,EAAE,WAAC,OAAA,CAAA,MAAA,IAAI,CAAC,IAAI,CAAC,GAAG,0CAAE,IAAI,MAAK,gBAAgB,CAAA,EAAA,CAAC,0CAAE,IAAI,CAAC,CAAC,EAAE,KAAK,CAC3F,CAAC;AACN,CAAC;AAJD,oDAIC"}

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@zenstackhq/openapi",
   "displayName": "ZenStack Plugin and Runtime for OpenAPI",
-  "version": "1.0.0-alpha.98",
+  "version": "1.0.0-beta.1",
   "description": "ZenStack plugin and runtime supporting OpenAPI",
   "main": "index.js",
   "repository": {
@@ -18,28 +18,34 @@
   "dependencies": {
     "@prisma/generator-helper": "^4.7.1",
     "change-case": "^4.1.2",
+    "lower-case-first": "^2.0.2",
     "openapi-types": "^12.1.0",
     "tiny-invariant": "^1.3.1",
     "yaml": "^2.2.1",
-    "@zenstackhq/runtime": "1.0.0-alpha.98",
-    "@zenstackhq/sdk": "1.0.0-alpha.98"
+    "zod": "3.21.1",
+    "zod-validation-error": "^0.2.1",
+    "@zenstackhq/sdk": "1.0.0-beta.1",
+    "@zenstackhq/runtime": "1.0.0-beta.1"
   },
   "devDependencies": {
     "@prisma/internals": "^4.7.1",
     "@readme/openapi-parser": "^2.4.0",
-    "@types/jest": "^29.4.0",
+    "@types/jest": "^29.5.0",
+    "@types/lower-case-first": "^1.0.1",
+    "@types/pluralize": "^0.0.29",
     "@types/tmp": "^0.2.3",
     "@typescript-eslint/eslint-plugin": "^5.54.0",
     "@typescript-eslint/parser": "^5.54.0",
     "copyfiles": "^2.4.1",
     "eslint": "^8.35.0",
-    "jest": "^29.4.3",
+    "jest": "^29.5.0",
+    "pluralize": "^8.0.0",
     "rimraf": "^3.0.2",
     "tmp": "^0.2.1",
     "ts-jest": "^29.0.5",
     "typescript": "^4.9.5",
-    "@zenstackhq/testtools": "1.0.0-alpha.98",
-    "zenstack": "1.0.0-alpha.98"
+    "@zenstackhq/testtools": "1.0.0-beta.1",
+    "zenstack": "1.0.0-beta.1"
   },
   "scripts": {
     "clean": "rimraf dist",

package/plugin.zmodel

@@ -1,9 +1,9 @@
-/*
+/**
  * Mark a data model to be ignored when generating OpenAPI specification.
  */
 attribute @@openapi.ignore()
 
-/*
+/**
  * Provide metadata for a data model for generating OpenAPI specification.
  */
 attribute @@openapi.meta(_ meta: Object)

package/rest-generator.d.ts

@@ -0,0 +1,36 @@
+import { OpenAPIGeneratorBase } from './generator-base';
+/**
+ * Generates RESTful style OpenAPI specification.
+ */
+export declare class RESTfulOpenAPIGenerator extends OpenAPIGeneratorBase {
+    private warnings;
+    generate(): string[];
+    private generatePaths;
+    private generatePathsForModel;
+    private makeResourceList;
+    private makeResourceCreate;
+    private makeResourceFetch;
+    private makeRelatedFetch;
+    private makeResourceUpdate;
+    private makeResourceDelete;
+    private makeRelationshipFetch;
+    private makeRelationshipCreate;
+    private makeRelationshipUpdate;
+    private generateFilterParameters;
+    private makeFilterParameter;
+    private generateComponents;
+    private generateSharedComponents;
+    private generateParameters;
+    private generateEnumComponent;
+    private generateDataModelComponents;
+    private generateModelEntity;
+    private generateField;
+    private get specVersion();
+    private fieldTypeToOpenAPISchema;
+    private ref;
+    private nullable;
+    private parameter;
+    private forbidden;
+    private notFound;
+    private success;
+}