[incomplete] Allow external references

bin/index.js

@@ -2,6 +2,8 @@
 
 'use strict';
 
+require('source-map-support/register');
+
 const path = require('path');
 const program = require('commander');
 const pkg = require('../package.json');

package.json

@@ -58,14 +58,19 @@
         "prettier": "prettier \"./src/**/*.ts\" \"./bin/index.js\" \"./types/index.d.ts\" --check",
         "prettier:fix": "prettier \"./src/**/*.ts\" \"./bin/index.js\" \"./types/index.d.ts\" --write",
         "prepublish": "yarn run clean && yarn run release",
-        "codecov": "codecov --token=66c30c23-8954-4892-bef9-fbaed0a2e42b"
+        "codecov": "codecov --token=66c30c23-8954-4892-bef9-fbaed0a2e42b",
+        "prepare": "yarn run release"
     },
     "dependencies": {
         "camelcase": "6.2.0",
         "commander": "6.2.0",
         "handlebars": "4.7.6",
         "js-yaml": "3.14.0",
         "mkdirp": "1.0.4",
+        "path": "0.12.7",
+        "pkg-dir": "^5.0.0",
+        "rimraf": "3.0.2",
+        "source-map-support": "^0.5.19",
         "rimraf": "3.0.2"
     },
     "devDependencies": {

src/index.ts

@@ -1,3 +1,6 @@
+import * as path from 'path';
+import * as pkgdir from 'pkg-dir';
+
 import { parse as parseV2 } from './openApi/v2';
 import { parse as parseV3 } from './openApi/v3';
 import { getOpenApiSpec } from './utils/getOpenApiSpec';
@@ -54,6 +57,11 @@ export async function generate({
     write = true,
 }: Options): Promise<void> {
     const openApi = isString(input) ? await getOpenApiSpec(input) : input;
+    const basePath = isString(input) ? path.resolve(path.dirname(input)) : process.cwd();
+    openApi.$meta = {
+        baseUri: `file://${basePath}/`, // use the baseURI of the openapi.yml file
+        projectPath: `${pkgdir.sync()}/`, // find the current project's base path
+    };
     const openApiVersion = getOpenApiVersion(openApi);
     const templates = registerHandlebarTemplates();
 
@@ -67,7 +75,7 @@ export async function generate({
         }
 
         case OpenApiVersion.V3: {
-            const client = parseV3(openApi);
+            const client = await parseV3(openApi);
             const clientFinal = postProcessClient(client);
             if (!write) break;
             await writeClient(clientFinal, templates, output, httpClient, useOptions, useUnionTypes, exportCore, exportServices, exportModels, exportSchemas);

src/interfaces/OpenApiBase.ts

@@ -0,0 +1,5 @@
+import { ParserMeta } from './ParserMeta';
+
+export type OpenApiBase = {
+    $meta: ParserMeta;
+};

src/interfaces/ParserMeta.ts

@@ -0,0 +1,9 @@
+export interface ParserMeta {
+    /**
+     * The base URI where the OpenAPI specification
+     * is stored. Used to resolve relative $ref
+     * to external files
+     */
+    baseUri: string;
+    projectPath: string;
+}

src/openApi/v2/interfaces/OpenApi.d.ts

@@ -1,3 +1,4 @@
+import { ParserMeta } from '../../../interfaces/ParserMeta';
 import type { Dictionary } from '../../../utils/types';
 import type { OpenApiExternalDocs } from './OpenApiExternalDocs';
 import type { OpenApiInfo } from './OpenApiInfo';
@@ -28,4 +29,5 @@ export interface OpenApi {
     security?: OpenApiSecurityRequirement[];
     tags?: OpenApiTag[];
     externalDocs?: OpenApiExternalDocs;
+    $meta: ParserMeta;
 }

src/openApi/v2/parser/getRef.ts

@@ -1,26 +1,58 @@
+import * as fs from 'fs';
+import * as path from 'path';
+
 import type { OpenApi } from '../interfaces/OpenApi';
 import type { OpenApiReference } from '../interfaces/OpenApiReference';
 
+function retrieveFile(projectPath: string, filePath: string) {
+    const normalised = path.normalize(filePath);
+    if (!normalised.startsWith(projectPath)) {
+        throw new Error(`$ref resolved path ${normalised} outside project directory ${projectPath}`);
+    }
+    try {
+        const fileContents = fs.readFileSync(normalised);
+        const fileString = fileContents.toString('utf8');
+        return JSON.parse(fileString);
+    } catch (error) {
+        throw new Error(`Unable to read referenced file ${normalised}: ${error.message}`);
+    }
+}
+
+function getRelativeReference<T>(openApi: OpenApi, ref: string): T {
+    // Fetch the paths to the definitions, this converts:
+    // "#/components/schemas/Form" to ["components", "schemas", "Form"]
+    const paths = ref
+        .replace(/^#/g, '')
+        .split('/')
+        .filter(item => item);
+
+    // Try to find the reference by walking down the path,
+    // if we cannot find it, then we throw an error.
+    let result: any = openApi;
+    paths.forEach((path: string): void => {
+        if (result.hasOwnProperty(path)) {
+            result = result[path];
+        } else {
+            throw new Error(`Could not find reference: "${ref}"`);
+        }
+    });
+    return result as T;
+}
 export function getRef<T>(openApi: OpenApi, item: T & OpenApiReference): T {
     if (item.$ref) {
-        // Fetch the paths to the definitions, this converts:
-        // "#/definitions/Form" to ["definitions", "Form"]
-        const paths = item.$ref
-            .replace(/^#/g, '')
-            .split('/')
-            .filter(item => item);
-
-        // Try to find the reference by walking down the path,
-        // if we cannot find it, then we throw an error.
-        let result: any = openApi;
-        paths.forEach((path: string): void => {
-            if (result.hasOwnProperty(path)) {
-                result = result[path];
+        if (item.$ref.startsWith('#')) {
+            // relative file reference
+            return getRelativeReference(openApi, item.$ref);
+        } else {
+            // URI reference - could be filesystem or remote
+            const uri = new URL(item.$ref, openApi.$meta.baseUri);
+            if (uri.protocol === 'file') {
+                const resolvedItem = retrieveFile(uri.pathname, openApi.$meta.projectPath);
+                return resolvedItem as T;
             } else {
-                throw new Error(`Could not find reference: "${item.$ref}"`);
+                throw new Error(`Cannot retrieve $ref item.$ref for protocol "${uri.protocol}"`);
             }
-        });
-        return result as T;
+        }
     }
     return item as T;
 }

src/openApi/v3/index.ts

@@ -10,11 +10,11 @@ import { getServiceVersion } from './parser/getServiceVersion';
  * all the models, services and schema's we should output.
  * @param openApi The OpenAPI spec  that we have loaded from disk.
  */
-export function parse(openApi: OpenApi): Client {
+export async function parse(openApi: OpenApi): Promise<Client> {
     const version = getServiceVersion(openApi.info.version);
     const server = getServer(openApi);
-    const models = getModels(openApi);
-    const services = getServices(openApi);
+    const models = await getModels(openApi);
+    const services = await getServices(openApi);
 
     return { version, server, models, services };
 }

src/openApi/v3/interfaces/OpenApi.d.ts

@@ -1,3 +1,4 @@
+import { ParserMeta } from '../../../interfaces/ParserMeta';
 import type { OpenApiComponents } from './OpenApiComponents';
 import type { OpenApiExternalDocs } from './OpenApiExternalDocs';
 import type { OpenApiInfo } from './OpenApiInfo';
@@ -18,4 +19,5 @@ export interface OpenApi {
     security?: OpenApiSecurityRequirement[];
     tags?: OpenApiTag[];
     externalDocs?: OpenApiExternalDocs;
+    $meta: ParserMeta;
 }

src/openApi/v3/interfaces/OpenApiParameter.d.ts

@@ -1,3 +1,4 @@
+import { ParserMeta } from '../../../interfaces/ParserMeta';
 import type { Dictionary } from '../../../utils/types';
 import type { OpenApiExample } from './OpenApiExample';
 import type { OpenApiReference } from './OpenApiReference';
@@ -20,4 +21,5 @@ export interface OpenApiParameter extends OpenApiReference {
     schema?: OpenApiSchema;
     example?: any;
     examples?: Dictionary<OpenApiExample>;
+    $meta: ParserMeta;
 }

src/openApi/v3/interfaces/OpenApiPath.d.ts

@@ -1,11 +1,13 @@
+import { OpenApiBase } from '../../../interfaces/OpenApiBase';
 import type { OpenApiOperation } from './OpenApiOperation';
 import type { OpenApiParameter } from './OpenApiParameter';
+import { OpenApiReference } from './OpenApiReference';
 import type { OpenApiServer } from './OpenApiServer';
 
 /**
  * https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.2.md#pathItemObject
  */
-export interface OpenApiPath {
+export interface OpenApiPath extends OpenApiReference, OpenApiBase {
     summary?: string;
     description?: string;
     get?: OpenApiOperation;

src/openApi/v3/interfaces/OpenApiRequestBody.d.ts

@@ -1,11 +1,12 @@
+import type { OpenApiBase } from '../../../interfaces/OpenApiBase';
 import type { Dictionary } from '../../../utils/types';
 import type { OpenApiMediaType } from './OpenApiMediaType';
 import type { OpenApiReference } from './OpenApiReference';
 
 /**
  * https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.2.md#requestBodyObject
  */
-export interface OpenApiRequestBody extends OpenApiReference {
+export interface OpenApiRequestBody extends OpenApiReference, OpenApiBase {
     description?: string;
     content: Dictionary<OpenApiMediaType>;
     required?: boolean;

src/openApi/v3/interfaces/OpenApiResponse.d.ts

@@ -1,3 +1,4 @@
+import type { OpenApiBase } from '../../../interfaces/OpenApiBase';
 import type { Dictionary } from '../../../utils/types';
 import type { OpenApiHeader } from './OpenApiHeader';
 import type { OpenApiLink } from './OpenApiLink';
@@ -7,7 +8,7 @@ import type { OpenApiReference } from './OpenApiReference';
 /**
  * https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.2.md#responseObject
  */
-export interface OpenApiResponse extends OpenApiReference {
+export interface OpenApiResponse extends OpenApiReference, OpenApiBase {
     description: string;
     headers?: Dictionary<OpenApiHeader>;
     content?: Dictionary<OpenApiMediaType>;

src/openApi/v3/interfaces/OpenApiSchema.d.ts

@@ -1,3 +1,4 @@
+import { ParserMeta } from '../../../interfaces/ParserMeta';
 import type { Dictionary } from '../../../utils/types';
 import type { WithEnumExtension } from './Extensions/WithEnumExtension';
 import type { OpenApiDiscriminator } from './OpenApiDiscriminator';
@@ -44,4 +45,5 @@ export interface OpenApiSchema extends OpenApiReference, WithEnumExtension {
     externalDocs?: OpenApiExternalDocs;
     example?: any;
     deprecated?: boolean;
+    $meta: ParserMeta;
 }