openapi-sync 1.0.24 → 1.0.25

package/README.md

@@ -1,37 +1,138 @@
 # Openapi-sync
 
-**Openapi-sync** is a developer-friendly tool designed to keep your API up-to-date by leveraging OpenAPI schemas. It automates the generation of endpoint URIs and type definitions, including shared types, directly from your OpenAPI specification. Whether you need real-time synchronization before commits or periodic updates, openapi-sync ensures your API structure is always current and consistent. With an easy-to-use CLI, this tool integrates seamlessly into your development workflow, making API maintenance simpler and more reliable.
+[![NPM Version](https://img.shields.io/npm/v/openapi-sync.svg)](https://www.npmjs.com/package/openapi-sync)
+[![License](https://img.shields.io/npm/l/openapi-sync.svg)](https://github.com/akintomiwa-fisayo/openapi-sync/blob/main/LICENSE)
+
+**Openapi-sync** is a powerful developer tool that automates the synchronization of your API documentation with your codebase using OpenAPI (formerly Swagger) specifications. It generates TypeScript types and endpoint definitions from your OpenAPI schema, ensuring your API documentation stays up-to-date with your code.
+
+## Features
+
+- 🔄 Real-time API Synchronization
+- 📝 Automatic Type Generation
+- 🔄 Periodic API Refetching
+- 📁 Configurable Output Directory
+- 🔄 Customizable Naming Conventions
+- 🔄 Endpoint URL Transformation
+- 🔄 Schema Validation
+- 🔄 CLI Integration
+- 🔄 TypeScript Support
+- 🔄 YAML and JSON Support
 
 ## Installation
 
-To install `openapi-sync`, run the following command:
+Install the package using npm:
 
 ```bash
 npm install openapi-sync
 ```
 
+Or use it directly via npx:
+
+```bash
+npx openapi-sync
+```
+
 ## Configuration
 
-Create an `openapi.sync.json` file at the root of your project to configure openapi-sync. You can use the provided [`openapi.sync.sample.json`](https://github.com/akintomiwa-fisayo/openapi-sync/blob/master/openapi.sync.sample.json) as reference.
+Create a `openapi.sync.json` file in your project root with the following structure:
+
+```json
+{
+  "refetchInterval": 5000, // milliseconds between API refetches
+  "folder": "/path/to/output", // output directory for generated files
+  "api": {
+    "example1": "https://api.example.com/openapi.json",
+    "example2": "https://api.example.com/openapi.yaml"
+  },
+  "naming": {
+    "replaceWords": [
+      {
+        "replace": "Api",
+        "with": "",
+        "type": "endpoint"
+      }
+    ]
+  },
+  "endpoints": {
+    "value": {
+      "replaceWords": [
+        {
+          "replace": "/api/v\\d/",
+          "with": ""
+        }
+      ]
+    }
+  }
+}
+```
 
 ## Usage
 
-To start using openapi-sync, simply run the following command in your terminal:
+### CLI Commands
 
 ```bash
+# Basic usage
 npx openapi-sync
+
+# With custom refetch interval
+npx openapi-sync --refreshinterval 30000
 ```
 
-You can also add it as a script in your package.json for easy access:
+### Programmatic Usage
 
-```json
-"scripts": {
-  "api-sync": "npx openapi-sync",
-}
+```typescript
+import { Init } from "openapi-sync";
+
+// Initialize with custom options
+await Init({
+  refetchInterval: 30000, // optional, defaults to config value
+});
 ```
 
-## Features
+## Output Generation
+
+The tool generates:
+
+1. TypeScript interfaces for API endpoints
+2. Type definitions for request/response bodies
+3. Shared component types
+4. Endpoint URL constants
+
+## Type Generation
+
+The tool supports:
+
+- Primitive types (string, number, boolean, etc.)
+- Complex types (objects, arrays)
+- Enums
+- Nullable types
+- Any types
+- Shared components
+- Request/response bodies
+
+## Error Handling
+
+The tool includes:
+
+- Network error retries
+- Schema validation
+- Type generation error handling
+- State persistence
+
+## API Documentation
+
+For detailed API documentation, please refer to the [OpenAPI specification](https://spec.openapis.org/oas/v3.0.3).
+
+## License
+
+This project is licensed under the ISC License - see the [LICENSE](LICENSE) file for details.
+
+## Support
+
+For support, please open an issue in the GitHub repository.
+
+## Acknowledgments
 
-- Automated Endpoint URI Generation: Effortlessly generate endpoint URIs from your OpenAPI schema.
-- Type Generation: Automatically create all types defined in your API schema, including shared types, for better code consistency.
+- Thanks to the OpenAPI Initiative for the OpenAPI specification
+- Thanks to all contributors and users of this package
 - Flexible CLI Commands: Sync your API at any point in the development process on app start, pre-commit, or via manual triggers.

package/dist/Openapi-sync/components/helpers.js

@@ -64,7 +64,7 @@ const capitalize = (text) => {
     return capitalizedWord;
 };
 exports.capitalize = capitalize;
-const getSharedComponentName = (componentName) => `IApi${(0, exports.capitalize)(componentName)}`;
+const getSharedComponentName = (componentName, componentType) => `IApi${(0, exports.capitalize)(componentName)}`;
 exports.getSharedComponentName = getSharedComponentName;
 const getEndpointDetails = (path, method) => {
     const pathParts = path.split("/");
@@ -106,17 +106,23 @@ const getEndpointDetails = (path, method) => {
 };
 exports.getEndpointDetails = getEndpointDetails;
 const parseSchemaToType = (apiDoc, schema, name, isRequired, options) => {
-    let typeName = name ? `\t"${name}"${isRequired ? "" : "?"}: ` : "";
+    let overrideName = "";
+    let componentName = "";
     let type = "";
     if (schema) {
         if (schema.$ref) {
+            // console.log("Type schema 2");
             if (schema.$ref[0] === "#") {
                 let pathToComponentParts = (schema.$ref || "").split("/");
                 pathToComponentParts.shift();
                 const pathToComponent = pathToComponentParts.join(".");
                 const component = lodash_1.default.get(apiDoc, pathToComponent, null);
+                // console.log("Type schema 3", pathToComponentParts);
                 if (component) {
-                    const componentName = pathToComponentParts[pathToComponentParts.length - 1];
+                    if (component === null || component === void 0 ? void 0 : component.name) {
+                        overrideName = component.name;
+                    }
+                    componentName = pathToComponentParts[pathToComponentParts.length - 1];
                     // Reference component via import instead of parsing
                     type += `${(options === null || options === void 0 ? void 0 : options.noSharedImport) ? "" : "Shared."}${(0, exports.getSharedComponentName)(componentName)}`;
                     // type += `${parseSchemaToType(apiDoc, component, "", isRequired)}`;
@@ -210,9 +216,14 @@ const parseSchemaToType = (apiDoc, schema, name, isRequired, options) => {
         //Default type to string if no schema provided
         type = "string";
     }
+    let _name = overrideName || name;
+    if ((options === null || options === void 0 ? void 0 : options.useComponentName) && !_name) {
+        _name = componentName;
+    }
+    let typeName = _name ? `\t"${_name}"${isRequired ? "" : "?"}: ` : "";
     const nullable = (schema === null || schema === void 0 ? void 0 : schema.nullable) ? " | null" : "";
     return type.length > 0
-        ? `${typeName}${type}${nullable}${name ? ";\n" : ""}`
+        ? `${typeName}${type}${nullable}${_name ? ";\n" : ""}`
         : "";
 };
 exports.parseSchemaToType = parseSchemaToType;

package/dist/Openapi-sync/index.js

@@ -71,18 +71,46 @@ const OpenapiSync = (apiUrl, apiName, refetchInterval) => __awaiter(void 0, void
     (0, state_1.setState)(apiName, spec);
     let endpointsFileContent = "";
     let typesFileContent = "";
-    let sharedTypesFileContent = "";
-    if (spec.components && spec.components.schemas) {
-        // Create components (shared) types
-        const components = spec.components.schemas;
-        const contentKeys = Object.keys(components);
-        // only need 1 schema so will us the first schema provided
-        contentKeys.forEach((key) => {
-            const typeCnt = `${(0, helpers_1.parseSchemaToType)(spec, components[key], "", true, {
-                noSharedImport: true,
-            })}`;
-            if (typeCnt) {
-                sharedTypesFileContent += `export type ${(0, helpers_1.getSharedComponentName)(key)} = ${typeCnt};\n`;
+    let sharedTypesFileContent = {};
+    if (spec.components) {
+        Object.keys(spec.components).forEach((key) => {
+            if ([
+                "schemas",
+                "responses",
+                "parameters",
+                "examples",
+                "requestBodies",
+                "headers",
+                "links",
+                "callbacks",
+            ].includes(key)) {
+                // Create components (shared) types
+                const components = spec.components[key];
+                const contentKeys = Object.keys(components);
+                // only need 1 schema so will us the first schema provided
+                contentKeys.forEach((contentKey) => {
+                    var _a, _b;
+                    /*  const schema = (() => {
+                      switch (key) {
+                        case "parameters":
+                          return components[contentKey].schema;
+                        default:
+                          return components[contentKey];
+                      }
+                    })() as IOpenApSchemaSpec; */
+                    const schema = (((_a = components[contentKey]) === null || _a === void 0 ? void 0 : _a.schema)
+                        ? components[contentKey].schema
+                        : components[contentKey]);
+                    const typeCnt = `${(0, helpers_1.parseSchemaToType)(spec, schema, "", true, {
+                        noSharedImport: true,
+                        useComponentName: ["parameters"].includes(key),
+                    })}`;
+                    if (typeCnt) {
+                        sharedTypesFileContent[key] =
+                            ((_b = sharedTypesFileContent[key]) !== null && _b !== void 0 ? _b : "") +
+                                `export type ${(0, helpers_1.getSharedComponentName)(contentKey)} = ${typeCnt};\n`;
+                    }
+                });
             }
         });
     }
@@ -152,9 +180,9 @@ const OpenapiSync = (apiUrl, apiName, refetchInterval) => __awaiter(void 0, void
                 // create query parameters types
                 const parameters = (_b = endpointSpec[method]) === null || _b === void 0 ? void 0 : _b.parameters;
                 let typeCnt = "";
-                parameters.forEach((param) => {
-                    if (param.in === "query" && param.name) {
-                        typeCnt += `${(0, helpers_1.parseSchemaToType)(spec, param.schema, param.name, param.required)}`;
+                parameters.forEach((param, i) => {
+                    if (param.$ref || (param.in === "query" && param.name)) {
+                        typeCnt += `${(0, helpers_1.parseSchemaToType)(spec, param.$ref ? param : param.schema, param.name || "", param.required)}`;
                     }
                 });
                 if (typeCnt) {
@@ -187,21 +215,21 @@ const OpenapiSync = (apiUrl, apiName, refetchInterval) => __awaiter(void 0, void
     yield fs_1.default.promises.mkdir(path_1.default.dirname(endpointsFilePath), { recursive: true });
     // Create the file asynchronously
     yield fs_1.default.promises.writeFile(endpointsFilePath, endpointsFileContent);
-    if (sharedTypesFileContent.length > 0) {
+    if (Object.values(sharedTypesFileContent).length > 0) {
         // Create the necessary directories
         const sharedTypesFilePath = path_1.default.join(rootUsingCwd, folderPath, "types", "shared.ts");
         yield fs_1.default.promises.mkdir(path_1.default.dirname(sharedTypesFilePath), {
             recursive: true,
         });
         // Create the file asynchronously
-        yield fs_1.default.promises.writeFile(sharedTypesFilePath, sharedTypesFileContent);
+        yield fs_1.default.promises.writeFile(sharedTypesFilePath, Object.values(sharedTypesFileContent).join("\n"));
     }
     if (typesFileContent.length > 0) {
         // Create the necessary directories
         const typesFilePath = path_1.default.join(rootUsingCwd, folderPath, "types", "index.ts");
         yield fs_1.default.promises.mkdir(path_1.default.dirname(typesFilePath), { recursive: true });
         // Create the file asynchronously
-        yield fs_1.default.promises.writeFile(typesFilePath, `${sharedTypesFileContent.length > 0
+        yield fs_1.default.promises.writeFile(typesFilePath, `${Object.values(sharedTypesFileContent).length > 0
             ? `import * as  Shared from "./shared";\n\n`
             : ""}${typesFileContent}`);
     }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "openapi-sync",
-  "version": "1.0.24",
+  "version": "1.0.25",
   "description": "A developer-friendly tool designed to keep your API up-to-date by leveraging OpenAPI schemas. It automates the generation of endpoint URIs and type definitions, including shared types, directly from your OpenAPI specification.",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",