Ralph dae9cfa415
Make plugins documentation generation optional (#5465)
* Make plugins documentation generation optional

Signed-off-by: Ralph Maroun <rmaroun@outlook.com>

* Removing "-" character from schema names for generated plugin documentation so it becomes compatible with AWS API gateway import API feature using OAS file. Adding only one property to the settings file pluginsForWhichToGenerateDoc so that the user can choose for which plugin he wishes to generate documentation. Adding a parameter to generate or not the default response (this can now be set to false to have a documentation that is compatible with AWS API Gateway).

Signed-off-by: Ralph Maroun <rmaroun@outlook.com>

* Updating settings.json to start without the pluginsForWhichToGenerateDoc key so that all plugins documentation gets generated by default. Updated the documentation to reflect this change.

Signed-off-by: Ralph Maroun <rmaroun@outlook.com>

* Updating documentation to correct typos and rephrase some sentences to make them more clear.

Signed-off-by: Ralph Maroun <rmaroun@outlook.com>

* Destructuring the config to the var pluginsForWhichToGenerateDoc instead of renaming it to take into account comment from Alexandre Bodin

Signed-off-by: Ralph Maroun <rmaroun@outlook.com>

* Destructuring generateDefaultResponse and pluginsForWhichToGenerateDoc from strapi config object based on feedback from Alexandre Bodin

Signed-off-by: Ralph Maroun <rmaroun@outlook.com>

Co-authored-by: Alexandre BODIN <alexandrebodin@users.noreply.github.com>
2020-03-20 14:03:51 +01:00

124 lines
4.0 KiB
JavaScript
Executable File

const fs = require('fs');
const path = require('path');
const _ = require('lodash');
module.exports = async () => {
// Check if the plugin users-permissions is installed because the documentation needs it
if (Object.keys(strapi.plugins).indexOf('users-permissions') === -1) {
throw new Error(
'In order to make the documentation plugin works the users-permissions one is required'
);
}
const pluginStore = strapi.store({
environment: '',
type: 'plugin',
name: 'documentation',
});
const restrictedAccess = await pluginStore.get({ key: 'config' });
if (!restrictedAccess) {
pluginStore.set({ key: 'config', value: { restrictedAccess: false } });
}
let shouldUpdateFullDoc = false;
const services = strapi.plugins['documentation'].services.documentation;
// Generate plugins' documentation
const pluginsWithDocumentationNeeded = services.getPluginsWithDocumentationNeeded();
pluginsWithDocumentationNeeded.forEach(plugin => {
const isDocExisting = services.checkIfPluginDocumentationFolderExists(
plugin
);
if (!isDocExisting) {
services.createDocumentationDirectory(
services.getPluginDocumentationPath(plugin)
);
// create the overrides directory
services.createDocumentationDirectory(
services.getPluginOverrideDocumentationPath(plugin)
);
services.createPluginDocumentationFile(plugin);
shouldUpdateFullDoc = true;
} else {
const needToUpdatePluginDoc = services.checkIfPluginDocNeedsUpdate(
plugin
);
if (needToUpdatePluginDoc) {
services.createPluginDocumentationFile(plugin);
shouldUpdateFullDoc = true;
}
}
});
// Retrieve all the apis from the apis directory
const apis = services.getApis();
// Generate APIS' documentation
apis.forEach(api => {
const isDocExisting = services.checkIfDocumentationFolderExists(api);
if (!isDocExisting) {
// If the documentation directory doesn't exist create it
services.createDocumentationDirectory(services.getDocumentationPath(api));
// Create the overrides directory
services.createDocumentationDirectory(
services.getDocumentationOverridesPath(api)
);
// Create the documentation files per version
services.createDocumentationFile(api); // Then create the {api}.json documentation file
shouldUpdateFullDoc = true;
} else {
const needToUpdateAPIDoc = services.checkIfAPIDocNeedsUpdate(api);
if (needToUpdateAPIDoc) {
services.createDocumentationFile(api);
shouldUpdateFullDoc = true;
}
}
});
const fullDoc = services.generateFullDoc();
// Verify that the correct documentation folder exists in the documentation plugin
const isMergedDocumentationExists = services.checkIfMergedDocumentationFolderExists();
const documentationPath = services.getMergedDocumentationPath();
if (isMergedDocumentationExists) {
/**
* Retrieve all tags from the documentation and join them
* @param {Object} documentation
* @returns {String}
*/
const getDocTagsToString = documentation => {
return _.get(documentation, 'tags', [])
.map(tag => {
return tag.name.toLowerCase();
})
.sort((a, b) => a - b)
.join('.');
};
const oldDoc = require(path.resolve(
documentationPath,
'full_documentation.json'
));
const oldDocTags = getDocTagsToString(oldDoc);
const currentDocTags = getDocTagsToString(fullDoc);
// If the tags are different (an api has been deleted) we need to rebuild the documentation
if (oldDocTags !== currentDocTags) {
shouldUpdateFullDoc = true;
}
}
if (!isMergedDocumentationExists || shouldUpdateFullDoc) {
// Create the folder
services.createDocumentationDirectory(documentationPath);
// Write the file
fs.writeFileSync(
path.resolve(documentationPath, 'full_documentation.json'),
JSON.stringify(fullDoc, null, 2),
'utf8'
);
}
};