Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Added support for injecting MD files. Any extension starts with 'x-md… #327

Open
wants to merge 5 commits into
base: main
Choose a base branch
from
Open

Added support for injecting MD files. Any extension starts with 'x-md… #327

Changes from 1 commit
Commits
Show all changes
5 commits
Select commit Hold shift + click to select a range
efb9873
Added support for injecting MD files. Any extension starts with 'x-md…
May 18, 2020
ba52492
Moved loadMD to common.js, changed it to be sync instead of async, an…
Jun 2, 2020
ac89547
Added support to loadMD anywhere OpenAPISpec allows extensions, added…
Jun 2, 2020
84ae4a6
Merge branch 'master' of https://github.com/Mermade/widdershins
Jun 2, 2020
3b45427
Added default value for loadMdPrefix and changed loadMD to log except…
Jun 29, 2020
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
177 changes: 107 additions & 70 deletions lib/openapi3.js
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -18,22 +18,35 @@ const dereference = require('reftools/lib/dereference.js').dereference;
const clone = require('reftools/lib/clone.js').circularClone;
const swagger2openapi = require('swagger2openapi');

const fs = require('fs').promises;

const common = require('./common.js');

let templates;

function convertToToc(source, data) {
async function loadMD(sourceSection, destSection) {
for (let field in sourceSection) {
if (field.startsWith("x-md-")) {
//Replacing '-' so that field can be used in dot templates
let newFieldName = field.replace("x-md-", "md_");
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Should we replace all - with _ not just the first two? Either with a split/join or a .replace.

destSection[newFieldName] = await fs.readFile(sourceSection[field], 'utf8');
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Missing error handling on the readFile.

}
}
}

async function convertToToc(source, data) {
let resources = {};
resources[data.translations.defaultTag] = { count: 0, methods: {} };
resources[data.translations.defaultTag] = {count: 0, methods: {}};
if (source.tags) {
for (let tag of source.tags) {
resources[tag.name] = { count: 0, methods: {}, description: tag.description, externalDocs: tag.externalDocs };
resources[tag.name] = {count: 0, methods: {}, description: tag.description, externalDocs: tag.externalDocs};
}
}
for (var p in source.paths) {
if (!p.startsWith('x-')) {
for (var m in source.paths[p]) {
if ((m !== 'parameters') && (m !== 'summary') && (m !== 'description') && (!m.startsWith('x-'))) {

var method = {};
method.operation = source.paths[p][m];
method.pathItem = source.paths[p];
Expand All @@ -53,14 +66,21 @@ function convertToToc(source, data) {
tagDescription = tagData.description;
}
if (!resources[tagName]) {
resources[tagName] = { count: 0, methods: {}, description: tagDescription };
resources[tagName] = {count: 0, methods: {}, description: tagDescription};
}
resources[tagName].count++;
resources[tagName].methods[sMethodUniqueName] = method;
await loadMD(source.paths[p], resources[tagName]);
}
}
}
}


for (let tag of source.tags) {
//Load MD for tags
await loadMD(tag, resources[tag.name]);
}
for (let r in resources) {
if (resources[r].count <= 0) delete resources[r];
}
Expand All @@ -71,11 +91,11 @@ function getTagGroup(tag, tagGroups) {
if (tagGroups) {
for (let group of tagGroups) {
if (group.tags.indexOf(tag) > -1) {
return { name: group.title, description: group.description };
return {name: group.title, description: group.description};
}
}
}
return { name: tag, description: '' };
return {name: tag, description: ''};
}

function fakeProdCons(data) {
Expand Down Expand Up @@ -104,8 +124,7 @@ function fakeProdCons(data) {
let schema = op.requestBody.content[rb].schema;
if (schema['x-widdershins-oldRef']) {
data.bodyParameter.refName = schema['x-widdershins-oldRef'].replace('#/components/schemas/', '');
}
else {
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This is the first of many unrelated formatting changes even with GitHub diff set to ignore whitespace changes. Could we lose these please?

} else {
if ((schema.type === 'array') && (schema.items) && (schema.items['x-widdershins-oldRef'])) {
data.bodyParameter.refName = schema.items['x-widdershins-oldRef'].replace('#/components/schemas/', '');
}
Expand All @@ -117,14 +136,15 @@ function fakeProdCons(data) {
let key = Object.keys(op.requestBody.content[rb].examples)[0];
data.bodyParameter.exampleValues.object = op.requestBody.content[rb].examples[key].value;
data.bodyParameter.exampleValues.description = op.requestBody.content[rb].examples[key].description;
}
else {
data.bodyParameter.exampleValues.object = common.getSample(op.requestBody.content[rb].schema, data.options, { skipReadOnly: true, quiet: true }, data.api);
} else {
data.bodyParameter.exampleValues.object = common.getSample(op.requestBody.content[rb].schema, data.options, {
skipReadOnly: true,
quiet: true
}, data.api);
}
if (typeof data.bodyParameter.exampleValues.object === 'object') {
data.bodyParameter.exampleValues.json = safejson(data.bodyParameter.exampleValues.object, null, 2);
}
else {
} else {
data.bodyParameter.exampleValues.json = data.bodyParameter.exampleValues.object;
}
}
Expand Down Expand Up @@ -201,11 +221,13 @@ function getParameters(data) {
if (param.refName) param.safeType = '[' + param.refName + '](#schema' + param.refName.toLowerCase() + ')';
}
if (pSchema) {
param.exampleValues.object = param.example || param.default || common.getSample(pSchema, data.options, { skipReadOnly: true, quiet: true }, data.api);
param.exampleValues.object = param.example || param.default || common.getSample(pSchema, data.options, {
skipReadOnly: true,
quiet: true
}, data.api);
if (typeof param.exampleValues.object === 'object') {
param.exampleValues.json = safejson(param.exampleValues.object, null, 2);
}
else {
} else {
param.exampleValues.json = "'" + param.exampleValues.object + "'";
}
}
Expand Down Expand Up @@ -266,8 +288,7 @@ function getParameters(data) {
if (data.operation.security.length) {
effSecurity = Object.keys(data.operation.security[0]);
}
}
else if (data.api.security && data.api.security.length) {
} else if (data.api.security && data.api.security.length) {
effSecurity = Object.keys(data.api.security[0]);
}
if (effSecurity && effSecurity.length && data.api.components && data.api.components.securitySchemes) {
Expand All @@ -285,8 +306,7 @@ function getParameters(data) {
authHeader.exampleValues.object = 'Bearer {access-token}';
authHeader.exampleValues.json = "'" + authHeader.exampleValues.object + "'";
data.allHeaders.push(authHeader);
}
else if ((secScheme.type === 'apiKey') && (secScheme.in === 'header')) {
} else if ((secScheme.type === 'apiKey') && (secScheme.in === 'header')) {
let authHeader = {};
authHeader.name = secScheme.name;
authHeader.type = 'string';
Expand Down Expand Up @@ -325,8 +345,7 @@ function getBodyParameterExamples(data) {
let xmlWrap = false;
if (data.bodyParameter.schema && data.bodyParameter.schema.xml) {
xmlWrap = data.bodyParameter.schema.xml.name;
}
else if (data.bodyParameter.schema && data.bodyParameter.schema["x-widdershins-oldRef"]) {
} else if (data.bodyParameter.schema && data.bodyParameter.schema["x-widdershins-oldRef"]) {
xmlWrap = data.bodyParameter.schema["x-widdershins-oldRef"].split('/').pop();
}
if (common.doContentType(data.consumes, 'json')) {
Expand Down Expand Up @@ -384,7 +403,7 @@ function fakeBodyParameter(data) {

if ((param.schema.type === 'object') && (data.options.expandBody || (!param.schema["x-widdershins-oldRef"]))) {
let offset = (data.options.omitBody ? -1 : 0);
let props = common.schemaToArray(data.bodyParameter.schema, offset, { trim: true }, data);
let props = common.schemaToArray(data.bodyParameter.schema, offset, {trim: true}, data);

for (let block of props) {
for (let prop of block.rows) {
Expand All @@ -409,7 +428,9 @@ function fakeBodyParameter(data) {
function mergePathParameters(data) {
if (!data.parameters || !Array.isArray(data.parameters)) data.parameters = [];
data.parameters = data.parameters.concat(data.method.pathParameters || []);
data.parameters = data.parameters.filter((param, index, self) => self.findIndex((p) => { return p.name === param.name && p.in === param.in; }) === index || param.in === 'body');
data.parameters = data.parameters.filter((param, index, self) => self.findIndex((p) => {
return p.name === param.name && p.in === param.in;
}) === index || param.in === 'body');
}

function getResponses(data) {
Expand Down Expand Up @@ -441,8 +462,7 @@ function getResponses(data) {
let schemaName = contentType.schema["x-widdershins-oldRef"].replace('#/components/schemas/', '');
entry.schema = '[' + schemaName + '](#schema' + schemaName.toLowerCase() + ')';
entry.$ref = true;
}
else {
} else {
if (contentType.schema && contentType.schema.type && (contentType.schema.type !== 'object') && (contentType.schema.type !== 'array')) {
entry.schema = contentType.schema.type;
}
Expand All @@ -460,12 +480,10 @@ function convertExample(ex) {
if (typeof ex === 'string') {
try {
return yaml.parse(ex);
}
catch (e) {
} catch (e) {
return ex;
}
}
else return ex;
} else return ex;
}

function getResponseExamples(data) {
Expand All @@ -482,13 +500,19 @@ function getResponseExamples(data) {
if (contentType.examples) {
for (let ctei in contentType.examples) {
let example = contentType.examples[ctei];
examples.push({ description: example.description || response.description, value: common.clean(convertExample(example.value)), cta: cta });
examples.push({
description: example.description || response.description,
value: common.clean(convertExample(example.value)),
cta: cta
});
}
}
else if (contentType.example) {
examples.push({ description: resp + ' ' + data.translations.response, value: common.clean(convertExample(contentType.example)), cta: cta });
}
else if (contentType.schema) {
} else if (contentType.example) {
examples.push({
description: resp + ' ' + data.translations.response,
value: common.clean(convertExample(contentType.example)),
cta: cta
});
} else if (contentType.schema) {
let obj = contentType.schema;
let autoCT = '';
if (common.doContentType(cta, 'json')) autoCT = 'json';
Expand All @@ -501,11 +525,15 @@ function getResponseExamples(data) {
let xmlWrap = false;
if (obj && obj.xml && obj.xml.name) {
xmlWrap = obj.xml.name;
}
else if (obj["x-widdershins-oldRef"]) {
} else if (obj["x-widdershins-oldRef"]) {
xmlWrap = obj["x-widdershins-oldRef"].split('/').pop();
}
examples.push({ description: resp + ' ' + data.translations.response, value: common.getSample(obj, data.options, { skipWriteOnly: true, quiet: true }, data.api), cta: cta, xmlWrap: xmlWrap });
examples.push({
description: resp + ' ' + data.translations.response,
value: common.getSample(obj, data.options, {skipWriteOnly: true, quiet: true}, data.api),
cta: cta,
xmlWrap: xmlWrap
});
}
}
}
Expand Down Expand Up @@ -599,39 +627,42 @@ function getAuthenticationStr(data) {
}

function convertInner(api, options) {
return new Promise(function (resolve, reject) {
return new Promise(async function (resolve, reject) {
let defaults = {};
defaults.title = 'API';
defaults.language_tabs = [{ 'shell': 'Shell' }, { 'http': 'HTTP' }, { 'javascript': 'JavaScript' }, { 'ruby': 'Ruby' }, { 'python': 'Python' }, { 'php': 'PHP' }, { 'java': 'Java' }, { 'go': 'Go' }];
defaults.language_tabs = [{'shell': 'Shell'}, {'http': 'HTTP'}, {'javascript': 'JavaScript'}, {'ruby': 'Ruby'}, {'python': 'Python'}, {'php': 'PHP'}, {'java': 'Java'}, {'go': 'Go'}];
defaults.toc_footers = [];
defaults.includes = [];
defaults.search = true;
defaults.theme = 'darkula';
defaults.headings = 2;
defaults.templateCallback = function (template, stage, data) { return data; };
defaults.templateCallback = function (template, stage, data) {
return data;
};

options = Object.assign({}, defaults, options);

let data = {};
if (options.verbose) console.warn('starting deref', api.info.title);
if (api.components) {
data.components = clone(api.components);
}
else {
} else {
data.components = {};
}
data.api = dereference(api, api, { verbose: options.verbose, $ref: 'x-widdershins-oldRef' });
data.api = dereference(api, api, {verbose: options.verbose, $ref: 'x-widdershins-oldRef'});
if (options.verbose) console.warn('finished deref');

if (data.api.components && data.api.components.schemas && data.api.components.schemas["x-widdershins-oldRef"]) {
delete data.api.components.schemas["x-widdershins-oldRef"];
}
//Load root level MD
await loadMD(api, data);

if (typeof templates === 'undefined') {
templates = dot.process({ path: path.join(__dirname, '..', 'templates', 'openapi3') });
templates = dot.process({path: path.join(__dirname, '..', 'templates', 'openapi3')});
}
if (options.user_templates) {
templates = Object.assign(templates, dot.process({ path: options.user_templates }));
templates = Object.assign(templates, dot.process({path: options.user_templates}));
}
data.options = options;
data.translations = {};
Expand Down Expand Up @@ -662,16 +693,14 @@ function convertInner(api, options) {
data.header = header;
data.title_prefix = (data.api.info && data.api.info.version ? common.slugify((data.api.info.title || '').trim() || 'API') : '');
data.templates = templates;
data.resources = convertToToc(api, data);
data.resources = await convertToToc(api, data);

if (data.api.servers && data.api.servers.length) {
data.servers = data.api.servers;
}
else if (options.loadedFrom) {
data.servers = [{ url: options.loadedFrom }];
}
else {
data.servers = [{ url: '//' }];
} else if (options.loadedFrom) {
data.servers = [{url: options.loadedFrom}];
} else {
data.servers = [{url: '//'}];
}
data.host = up.parse(data.servers[0].url).host;
data.protocol = up.parse(data.servers[0].url).protocol;
Expand All @@ -684,14 +713,18 @@ function convertInner(api, options) {
data.utils.yaml = yaml;
data.utils.inspect = util.inspect;
data.utils.safejson = safejson;
data.utils.isPrimitive = function (t) { return (t && (t !== 'object') && (t !== 'array')) };
data.utils.isPrimitive = function (t) {
return (t && (t !== 'object') && (t !== 'array'))
};
data.utils.toPrimitive = common.toPrimitive;
data.utils.slashes = function (s) { return s.replace(/\/+/g, '/').replace(':/', '://'); };
data.utils.slashes = function (s) {
return s.replace(/\/+/g, '/').replace(':/', '://');
};
data.utils.slugify = common.slugify;
data.utils.getSample = common.getSample;
data.utils.schemaToArray = common.schemaToArray;
data.utils.fakeProdCons = fakeProdCons;
data.utils.getParameters = getParameters;
data.utils.getParameters = getParameters;
data.utils.getCodeSamples = common.getCodeSamples;
data.utils.getBodyParameterExamples = getBodyParameterExamples;
data.utils.fakeBodyParameter = fakeBodyParameter;
Expand All @@ -708,15 +741,20 @@ function convertInner(api, options) {
let content = '';
if (!options.omitHeader) content += '---\n' + yaml.stringify(header) + '\n---\n\n';
data = options.templateCallback('main', 'pre', data);
if (data.append) { content += data.append; delete data.append; }
if (data.append) {
content += data.append;
delete data.append;
}
try {
content += templates.main(data);
}
catch (ex) {
} catch (ex) {
throw ex;
}
data = options.templateCallback('main', 'post', data);
if (data.append) { content += data.append; delete data.append; }
if (data.append) {
content += data.append;
delete data.append;
}
content = common.removeDupeBlankLines(content);

if (options.html) content = common.html(content, header, options);
Expand All @@ -727,15 +765,14 @@ function convertInner(api, options) {

function convert(api, options) {
if (options.resolve) {
return swagger2openapi.convertObj(api, { resolve: true, source: options.source, verbose: options.verbose })
.then(sOptions => {
return convertInner(sOptions.openapi, options);
})
.catch(err => {
console.error(err.message);
});
}
else {
return swagger2openapi.convertObj(api, {resolve: true, source: options.source, verbose: options.verbose})
.then(sOptions => {
return convertInner(sOptions.openapi, options);
})
.catch(err => {
console.error(err.message);
});
} else {
return convertInner(api, options);
}
}
Expand Down