strapi/packages/plugins/documentation/server/services/documentation.js

'use strict';

const path = require('path');
const fs = require('fs-extra');
const _ = require('lodash/fp');
const { produce } = require('immer');
const { getAbsoluteServerUrl } = require('@strapi/utils');
const { builApiEndpointPath, buildComponentSchema } = require('./helpers');

const defaultOpenApiComponents = require('./utils/default-openapi-components');
const { getPluginsThatNeedDocumentation } = require('./utils/get-plugins-that-need-documentation');

module.exports = ({ strapi }) => {
  const config = strapi.config.get('plugin.documentation');
  const pluginsThatNeedDocumentation = getPluginsThatNeedDocumentation(config);

  const overrideService = strapi.plugin('documentation').service('override');

  return {
    /**
     *
     * @deprecated
     * registerDoc is deprecated it will be removed in the next major release,
     * use strapi.plugin('documentation').service('override').registerOverride instead
     * @param {object} doc - The openapi specifcation to override
     * @param {object} options - The options to override the documentation
     * @param {string} options.pluginOrigin - The name of the plugin that is overriding the documentation
     * @param {string[]} options.excludeFromGeneration - The name of the plugin that is overriding the documentation
     */
    registerDoc(doc, options) {
      overrideService.registerOverride(doc, options);
    },

    getDocumentationVersion() {
      return _.get('info.version', config);
    },

    getFullDocumentationPath() {
      return path.join(strapi.dirs.app.extensions, 'documentation', 'documentation');
    },

    /**
     *
     * @deprecated
     * This method will be removed in the next major release
     */
    getCustomDocumentationPath() {
      return path.join(strapi.dirs.app.extensions, 'documentation', 'config', 'settings.json');
    },

    getDocumentationVersions() {
      return fs
        .readdirSync(this.getFullDocumentationPath())
        .map((version) => {
          try {
            const doc = JSON.parse(
              fs.readFileSync(
                path.resolve(this.getFullDocumentationPath(), version, 'full_documentation.json')
              )
            );

            const generatedDate = _.get(['info', 'x-generation-date'], doc);

            return { version, generatedDate, url: '' };
          } catch (err) {
            return null;
          }
        })
        .filter((x) => x);
    },

    /**
     * Returns settings stored in core-store
     */
    async getDocumentationAccess() {
      const { restrictedAccess } = await strapi
        .store({
          environment: '',
          type: 'plugin',
          name: 'documentation',
          key: 'config',
        })
        .get();

      return { restrictedAccess };
    },

    /**
     * @description - Gets the path for an api or plugin
     *
     * @param {object} api
     * @property {string} api.name - Name of the api
     * @property {string} api.getter - api | plugin
     *
     * @returns path to the api | plugin
     */
    getApiDocumentationPath(api) {
      if (api.getter === 'plugin') {
        return path.join(strapi.dirs.app.extensions, api.name, 'documentation');
      }

      return path.join(strapi.dirs.app.api, api.name, 'documentation');
    },

    async deleteDocumentation(version) {
      const apis = this.getPluginAndApiInfo();
      for (const api of apis) {
        await fs.remove(path.join(this.getApiDocumentationPath(api), version));
      }

      await fs.remove(path.join(this.getFullDocumentationPath(), version));
    },

    getPluginAndApiInfo() {
      const pluginsToDocument = pluginsThatNeedDocumentation.map((plugin) => {
        return {
          name: plugin,
          getter: 'plugin',
          ctNames: Object.keys(strapi.plugin(plugin).contentTypes),
        };
      });

      const apisToDocument = Object.keys(strapi.api).map((api) => {
        return {
          name: api,
          getter: 'api',
          ctNames: Object.keys(strapi.api[api].contentTypes),
        };
      });

      return [...apisToDocument, ...pluginsToDocument];
    },

    /**
     * @description - Creates the Swagger json files
     */
    async generateFullDoc(version = this.getDocumentationVersion()) {
      let paths = {};
      let schemas = {};
      const apis = this.getPluginAndApiInfo();

      const apisThatNeedGeneratedDocumentation = apis.filter(
        ({ name }) => !overrideService.excludedFromGeneration.includes(name)
      );
      for (const api of apisThatNeedGeneratedDocumentation) {
        const apiName = api.name;

        // TODO: check if this is necessary
        const apiDirPath = path.join(this.getApiDocumentationPath(api), version);
        // TODO: check if this is necessary
        const apiDocPath = path.join(apiDirPath, `${apiName}.json`);

        const apiPath = builApiEndpointPath(api);

        if (!apiPath) {
          continue;
        }

        // TODO: check if this is necessary
        await fs.ensureFile(apiDocPath);
        await fs.writeJson(apiDocPath, apiPath, { spaces: 2 });

        const componentSchema = buildComponentSchema(api);

        schemas = {
          ...schemas,
          ...componentSchema,
        };

        paths = { ...paths, ...apiPath };
      }

      const fullDocJsonPath = path.join(
        this.getFullDocumentationPath(),
        version,
        'full_documentation.json'
      );

      // Set config defaults
      const serverUrl = getAbsoluteServerUrl(strapi.config);
      const apiPath = strapi.config.get('api.rest.prefix');
      const generatedDocumentation = produce(config, (draft) => {
        // When no servers found set the default
        if (draft.servers.length === 0) {
          draft.servers = [
            {
              url: `${serverUrl}${apiPath}`,
              description: 'Development server',
            },
          ];
        }

        draft['x-strapi-config'].plugins = pluginsThatNeedDocumentation;
        // Delete it from the config so it doesn't end up in the spec
        delete draft['x-strapi-config'].customizer;

        // Set the generated paths
        draft.paths = paths;
        // Merge the generated component schemas with the defaults
        draft.components = _.merge(defaultOpenApiComponents, { schemas });

        overrideService.registeredOverrides.forEach((doc) => {
          if (doc.tags) {
            // Merge override tags with the generated tags
            draft.tags = draft.tags || [];
            draft.tags.push(...doc.tags);
          }

          if (doc.paths) {
            // Merge override paths with the generated paths
            // The override will add a new path or replace the value of an existing path
            draft.paths = { ...draft.paths, ...doc.paths };
          }

          if (doc.components) {
            Object.entries(doc.components).forEach(([key, val]) => {
              draft.components[key] = draft.components[key] || {};
              // Merge override components with the generated components,
              // The override will add a new component or replace the value of an existing component
              draft.components[key] = { ...draft.components[key], ...val };
            });
          }
        });
      });
      // Get the documentation customizer
      const documentationCustomizer = config['x-strapi-config'].customizer;
      // Escape hatch, allow the user to provide a customizer function that can manipulate
      // the generated documentation before it is written to the file system
      const finalDocumentation = documentationCustomizer
        ? produce(generatedDocumentation, documentationCustomizer)
        : generatedDocumentation;

      await fs.ensureFile(fullDocJsonPath);
      await fs.writeJson(fullDocJsonPath, finalDocumentation, { spaces: 2 });
    },
  };
};