Fix examples and resolve local references correctly

Author: fmvilas

README.md

@@ -28,6 +28,7 @@ npm install -g openapi3-generator
     -V, --version                  output the version number
     -o, --output <outputDir>       directory where to put the generated files (defaults to current directory)
     -t, --templates <templateDir>  directory where templates are located (defaults to internal templates directory)
+    -b, --basedir <baseDir>        directory to use as the base when resolving local file references (defaults to OpenAPI file directory)
     -h, --help                     output usage information
 ```
 

cli.js

@@ -13,6 +13,7 @@ const green = text => `\x1b[32m${text}\x1b[0m`;
 
 let openapiFile;
 let template;
+let baseDir;
 
 const parseOutput = dir => path.resolve(dir);
 
@@ -22,6 +23,7 @@ program
   .action((openapiFilePath, tmpl) => {
     if (!openapiFilePath.startsWith('http:') && !openapiFilePath.startsWith('https:')) {
       openapiFile = path.resolve(openapiFilePath);
+      baseDir = path.dirname(openapiFile);
     } else {
       openapiFile = openapiFilePath;
     }
@@ -30,6 +32,7 @@ program
   })
   .option('-o, --output <outputDir>', 'directory where to put the generated files (defaults to current directory)', parseOutput, process.cwd())
   .option('-t, --templates <templateDir>', 'directory where templates are located (defaults to internal nodejs templates)')
+  .option('-b, --basedir <baseDir>', 'directory to use as the base when resolving local file references (defaults to OpenAPI file directory)')
   .parse(process.argv);
 
 if (!openapiFile) {
@@ -39,6 +42,7 @@ if (!openapiFile) {
 
 generator.generate({
   openapi: openapiFile,
+  base_dir: program.basedir || baseDir || process.cwd(),
   target_dir: program.output,
   templates: program.templates ? path.resolve(process.cwd(), program.templates) : undefined,
   template,

lib/bundler.js

@@ -55,8 +55,8 @@ function parseContent (content) {
   }
 }
 
-async function dereference (json) {
-  return RefParser.dereference(json, {
+async function dereference (json, baseDir) {
+  return RefParser.dereference(`${baseDir}/`, json, {
     dereference: {
       circular: 'ignore'
     }
@@ -71,7 +71,7 @@ async function bundle (json) {
   });
 }
 
-async function bundler (filePath) {
+async function bundler (filePath, baseDir) {
   let content, parsedContent, dereferencedJSON, bundledJSON;
 
   try {
@@ -91,7 +91,7 @@ async function bundler (filePath) {
   }
 
   try {
-    dereferencedJSON = await dereference(parsedContent);
+    dereferencedJSON = await dereference(parsedContent, baseDir);
   } catch (e) {
     console.error('Can not dereference the JSON obtained from the content of the Swagger specification file');
     console.error(e);

lib/generator.js

@@ -256,10 +256,10 @@ const registerPartials = config => new Promise((resolve, reject) => {
   });
 });
 
-const bundle = async (openapi) => {
+const bundle = async (openapi, baseDir) => {
   if (typeof openapi === 'string') {
     try {
-      return await bundler(openapi);
+      return await bundler(openapi, baseDir);
     } catch (e) {
       throw e;
     }
@@ -278,7 +278,7 @@ const bundle = async (openapi) => {
  * @return {Promise}
  */
 codegen.generate = config => new Promise((resolve, reject) => {
-  bundle(config.openapi)
+  bundle(config.openapi, config.base_dir)
     .catch(reject)
     .then((openapi) => {
       openapi = beautifier(openapi);

templates/markdown/.partials/example.md

@@ -17,3 +17,10 @@
 ```
 {{/if}}
 {{/if}}
+
+{{#if externalValue}}
+{{#unless example}}
+##### Example
+{{/unless}}
+[Download example]({{externalValue}})
+{{/if}}

templates/markdown/.partials/operation.md

@@ -14,11 +14,16 @@
 ###### {{contentTypeName}}
 {{> schema schema=schema schemaName='body' hideTitle=true hideExamples=true}}
 
-{{> example example=schema.example generatedExample=schema.generatedExample }}
 {{#if examples}}
 {{#each examples as |example exampleName|}}
-{{> example example=example.value description=example.description}}
+{{> example example=example.value description=example.description externalValue=example.externalValue}}
 {{/each}}
+{{else}}
+{{#if example}}
+{{> example example=example.value description=example.description externalValue=example.externalValue}}
+{{else}}
+{{> example example=schema.example generatedExample=schema.generatedExample }}
+{{/if}}
 {{/if}}
 
 {{/each}}
@@ -29,11 +34,16 @@
 #### Request body
 {{> schema schema=../schema schemaName='body' hideTitle=true hideExamples=true}}
 
-{{> example example=schema.example generatedExample=schema.generatedExample }}
 {{#if ../examples}}
 {{#each ../examples as |example exampleName|}}
 {{> example example=example.value description=example.description}}
 {{/each}}
+{{else}}
+{{#if example}}
+{{> example example=example.value description=example.description }}
+{{else}}
+{{> example example=schema.example generatedExample=schema.generatedExample }}
+{{/if}}
 {{/if}}
 
 {{/equal}}

templates/markdown/.partials/schemas.md

@@ -1,7 +1,7 @@
-{{#if openapi.components.schemas}}
+{{#unless openapi.__noSchemas}}
 ## Schemas
 
 {{#each openapi.components.schemas}}
   {{~>schema schema=. schemaName=@key renderSlug=true~}}
 {{/each}}
-{{/if}}
+{{/unless}}