@akemona-org/strapi-plugin-documentation 3.7.0

package/LICENSE

@@ -0,0 +1,22 @@
+Copyright (c) 2015-present Strapi Solutions SAS
+
+Portions of the Strapi software are licensed as follows:
+
+* All software that resides under an "ee/" directory (the “EE Software”), if that directory exists, is licensed under the license defined in "ee/LICENSE".
+
+* All software outside of the above-mentioned directories or restrictions above is available under the "MIT Expat" license as set forth below.
+
+MIT Expat License
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,170 @@
+# Plugin documentation
+
+---
+
+## Deprecation Warning :warning:
+
+Hello! We have some news to share,
+
+We’ve decided it’ll soon be time to end the support for `strapi-plugin-documentation`.
+
+After years of iterations, Strapi is going to V4 and we won’t maintain V3 packages when it’ll reach its end-of-support milestone (~end of Q3 2022).
+
+If you’ve been using `strapi-plugin-documentation` and have migrated to V4 (or if you want to), you can find the equivalent and updated version of this package at this [URL](https://github.com/strapi/strapi/tree/master/packages/plugins/documentation) and with the following name on NPM: `@strapi/plugin-documentation`.
+
+If you’ve contributed to the development of this package, thank you again for that! We hope to see you on the V4 soon.
+
+The Akemona team
+
+---
+
+This plugin automates your API documentation creation. It basically generates a swagger file. It follows the [Open API specification version 3.0.1](https://swagger.io/specification/).
+The documentation plugin is not release on npm yet, Here's how to install it.
+
+## Usage
+
+- Config
+- Creating a new documentation version
+- Generated files
+  - full_documentation.json structure
+- Overriding the suggested documentation
+- FAQ
+  - How does it generate the others plugins documentation ?
+  - I have created a route into a common API (like product) that query another model. How to automate this?
+- TODO
+
+### Config
+
+The plugin comes with a `settings.json` file located in `./my-project/plugins/documentation/config` folder where you can specify all your environment variables, licenses, external documentation and so one...
+You can add all the entries listed in the [specification](https://swagger.io/specification/).
+
+_NOTE_ if you need to add a custom key you can do it by prefixing your key by `x-{something}`
+
+### Creating a new documentation version
+
+In order to create a new version you need to change the `info.version` key in the `settings.json` file.
+
+This will automatically create a new version.
+
+### Generated files
+
+When you start your server with this plugin installed it will automatically create the following files in your APIs (we will see how it works for the plugins).
+
+- api
+  - my-api
+    - documentation
+      - documentationVersion // 1.0.0
+        - my-api.json // File containing all the identified path
+        - unclassified.json // File containing the manually added paths
+        - overrides // Folder to override the generated documentation
+- plugins
+  - ...
+  - documentation
+    - documentation
+      - 1.0.0
+        - full_documentation.json
+
+#### full_documentation.json
+
+The combined documentation is merged into the `full_documentation.json` file and it's located in `./plugins/documentation/{version}/full_documentation.json`
+
+It has the following structure
+
+```
+{
+  "openapi": "3.0.0" // do not change this version
+  "info": {
+    "version": "1.0.0" // change this line to create a new version
+    ...
+  }
+  "x-strapi-config": {
+    "path": "/documentation", // Change this line to change to url of the doc
+    "showGeneratedFiles": true // Do not change this line at the moment...
+  },
+  "servers" {} // Your servers config (it will be automated),
+  "externalDocs": {},
+  "paths": {} // All your Api routes,
+  "tags": [] // Group of route
+  "components": {} // Default generated components and custom ones
+}
+```
+
+### Overriding the suggested documentation
+
+Currently the plugin writes a json file for each API.
+
+In order to customize the responses or to add information to a path you need to create a file in the associated `overrides/<file-name>.json` (the name of the file matters so make sure they are similar). Then you just need to identify the path you want to modify.
+You can modify the default generated tags by adding a new one at the end of the file. Same for the components.
+
+**_NOTE 1_**
+
+Overriding the `full_documentation.json` is a bad idea since it will be regenerated each time you change a model.
+
+**_NOTE 2_**
+
+You can easily modify the description, summary, parameters of a path however, for a response like the `200` you will need to write the full object. Take a look at the `./plugins/users-permissions/documentation/overrides/1.0.0/users-permissions-User.json` for a complete example.
+
+### FAQ
+
+#### How does it generate the others plugins documentation ?
+
+In other to reference a plugin's route into the documentation you need to add a `description` key in the `config` object.
+
+For example this is the plugin email routes.json file
+
+```
+{
+"routes": [
+  {
+    "method": "POST",
+    "path": "/",
+    "handler": "Email.send",
+    "config": {
+      "policies": [],
+      "description": "Send an email",
+      "tag": {
+        "plugin": "email",
+        "name": "Email"
+      }
+    }
+  },
+  {
+    "method": "GET",
+    "path": "/environments",
+    "handler": "Email.getEnvironments",
+    "config": {
+      "policies": []
+    }
+  },
+  {
+    "method": "GET",
+    "path": "/settings/:environment",
+    "handler": "Email.getSettings",
+    "config": {
+      "policies": []
+    }
+  },
+  {
+    "method": "PUT",
+    "path": "/settings/:environment",
+    "handler": "Email.updateSettings",
+    "config": {
+      "policies": []
+    }
+  }
+]
+}
+```
+
+In this file we have only one route that we want to reference in our documentation (`/`). Usually, the tag object is used for the SWAGGER UI, it will group this route under the `Email - Email` dropdown in the documentation. Furthermore, the algorithm will try to find the model to generate the best response possible. If the model is unknown it generates a response like the following `{ foo: "string" }` that you can easily override later.
+
+There's another property to guide the algorithm to create the best response possible, the `actionType` key.
+When we can't know by the controller name the type of the returned response (like `find` and `findOne`) you can specify it with this key. There's an example in `./plugins/users-permissions/config/routes.json`.
+
+#### I have created a route in a common API (like product) that query another model. How to automate this ?
+
+You can use the `tag` key in your route. If you provide a `tag` which is a string like `"tag": "Product"` the algorithm will know that the end-point retrieves data from the **`Product`** table. Creating a tag object `{ "tag": { "name": "User", "plugin": "User-Permissions } }` will result in generating a response with the **`User`** model from the plugin users-permissions.
+
+---
+
+Each entry of the object is easily customisable take look at the users-permissions ones they are a good example on how to do it.

package/admin/src/assets/images/logo.svg

@@ -0,0 +1 @@
+<svg width="24" height="22" xmlns="http://www.w3.org/2000/svg"><text transform="translate(-23 -7)" fill="#4B515A" fill-rule="evenodd" font-family="AppleColorEmoji, Apple Color Emoji" font-size="24"><tspan x="23" y="28">🗂</tspan></text></svg>

package/admin/src/components/Block/components.js

@@ -0,0 +1,26 @@
+import styled from 'styled-components';
+
+const Wrapper = styled.div`
+  margin-bottom: 28px;
+  background: #ffffff;
+  padding: 22px 28px 18px;
+  border-radius: 2px;
+  box-shadow: 0 2px 4px #e3e9f3;
+  -webkit-font-smoothing: antialiased;
+`;
+
+const Title = styled.div`
+  padding-top: 0px;
+  line-height: 18px;
+  > span {
+    font-weight: 600;
+    color: #333740;
+    font-size: 18px;
+  }
+  > p {
+    color: #787e8f;
+    font-size: 13px;
+  }
+`;
+
+export { Wrapper, Title };

package/admin/src/components/Block/index.js

@@ -0,0 +1,39 @@
+/**
+ *
+ * Block
+ */
+
+import React from 'react';
+import PropTypes from 'prop-types';
+import { FormattedMessage } from 'react-intl';
+import { Wrapper, Title } from './components';
+
+const renderMsg = msg => <p>{msg}</p>;
+
+const Block = ({ children, description, style, title }) => (
+  <div className="col-md-12">
+    <Wrapper style={style}>
+      <Title>
+        <FormattedMessage id={title} />
+        <FormattedMessage id={description}>{renderMsg}</FormattedMessage>
+      </Title>
+      {children}
+    </Wrapper>
+  </div>
+);
+
+Block.defaultProps = {
+  children: null,
+  description: 'app.utils.defaultMessage',
+  style: {},
+  title: 'app.utils.defaultMessage',
+};
+
+Block.propTypes = {
+  children: PropTypes.any,
+  description: PropTypes.string,
+  style: PropTypes.object,
+  title: PropTypes.string,
+};
+
+export default Block;

package/admin/src/components/Row/ButtonContainer.js

@@ -0,0 +1,53 @@
+import React from 'react';
+import PropTypes from 'prop-types';
+import { FormattedMessage } from 'react-intl';
+import { CheckPermissions } from 'strapi-helper-plugin';
+import pluginPermissions from '../../permissions';
+import openWithNewTab from '../../utils/openWithNewTab';
+import { StyledButton } from './components';
+
+const ButtonContainer = ({ currentDocVersion, isHeader, onClick, onClickDelete, version }) => {
+  if (isHeader) {
+    return <div />;
+  }
+
+  return (
+    <div>
+      <StyledButton
+        type="openDocumentation"
+        onClick={() => openWithNewTab(`/documentation/v${version}`)}
+      >
+        <FormattedMessage id="documentation.components.Row.open" />
+      </StyledButton>
+      <CheckPermissions permissions={pluginPermissions.regenerate}>
+        <StyledButton type="generateDocumentation" onClick={() => onClick(version)}>
+          <FormattedMessage id="documentation.components.Row.regenerate" />
+        </StyledButton>
+      </CheckPermissions>
+      <CheckPermissions permissions={pluginPermissions.update}>
+        <StyledButton
+          type={version === currentDocVersion ? '' : 'trash'}
+          onClick={() => onClickDelete(version)}
+        />
+      </CheckPermissions>
+    </div>
+  );
+};
+
+ButtonContainer.defaultProps = {
+  currentDocVersion: '1.0.0',
+  isHeader: false,
+  onClick: () => {},
+  onClickDelete: () => {},
+  version: '',
+};
+
+ButtonContainer.propTypes = {
+  currentDocVersion: PropTypes.string,
+  isHeader: PropTypes.bool,
+  onClick: PropTypes.func,
+  onClickDelete: PropTypes.func,
+  version: PropTypes.string,
+};
+
+export default ButtonContainer;

package/admin/src/components/Row/components.js

@@ -0,0 +1,83 @@
+import styled, { css } from 'styled-components';
+import { Button } from 'strapi-helper-plugin';
+
+const Wrapper = styled.div`
+  height: 54px;
+  display: flex;
+  line-height: 53px;
+  margin: 0 28px 0 36px;
+  justify-content: space-between;
+  border-bottom: 1px solid rgba(14, 22, 34, 0.04);
+  font-size: 13px;
+  color: #333740;
+  > div:first-child {
+    flex: 0 0 70px;
+    font-weight: 500;
+  }
+  > div:nth-child(2) {
+    flex: 0 0 160px;
+    text-align: left;
+    font-weight: 500 !important;
+  }
+  > div:last-child {
+    flex: 0 0 400px;
+    align-self: center;
+    text-align: right;
+  }
+  -webkit-font-smoothing: antialiased;
+`;
+
+const StyledButton = styled(Button)`
+  height: 26px;
+  margin: 0;
+  padding: 0 15px;
+  line-height: initial;
+  font-size: 13px;
+  font-weight: 500;
+  ${({ type }) => {
+  if (type === 'openDocumentation') {
+    return css`
+        margin-right: 10px;
+        border: 1px solid #dfe0e1;
+        &:before {
+          margin-right: 10px;
+          content: '\f08e';
+          font-family: 'FontAwesome';
+          font-size: 10px;
+        }
+      `;
+  }
+  if (type === 'generateDocumentation') {
+    return css`
+        background: #e6f0fb;
+        border: 1px solid #aed4fb;
+        color: #007eff;
+        &:before {
+          margin-right: 10px;
+          content: '\f021';
+          font-family: 'FontAwesome';
+          font-size: 10px;
+        }
+      `;
+  }
+  if (type === 'trash') {
+    return css`
+        margin-left: 25px;
+        font-weight: 400;
+        &:before {
+          margin-right: 10px;
+          content: '\f2ed';
+          font-family: 'FontAwesome';
+          font-size: 12 px;
+        }
+      `;
+  }
+
+  return css`
+      margin-left: 45px;
+      font-weight: 400;
+    `;
+}}
+`;
+
+export { Wrapper, StyledButton };

package/admin/src/components/Row/index.js

@@ -0,0 +1,57 @@
+/**
+ * Row
+ */
+
+import React from 'react';
+import { FormattedMessage } from 'react-intl';
+import PropTypes from 'prop-types';
+import ButtonContainer from './ButtonContainer';
+import { Wrapper } from './components';
+
+function Row({
+  currentDocVersion,
+  data,
+  isHeader,
+  onClickDelete,
+  onUpdateDoc,
+}) {
+  const { version, generatedDate } = data;
+
+  return (
+    <Wrapper>
+      <div>{version}</div>
+      <div>
+        {isHeader ? (
+          <FormattedMessage id="documentation.components.Row.generatedDate" />
+        ) : (
+          <span>{generatedDate}</span>
+        )}
+      </div>
+      <ButtonContainer
+        currentDocVersion={currentDocVersion}
+        isHeader={isHeader}
+        version={version}
+        onClickDelete={onClickDelete}
+        onClick={onUpdateDoc}
+      />
+    </Wrapper>
+  );
+}
+
+Row.defaultProps = {
+  currentDocVersion: '1.0.0',
+  data: {},
+  isHeader: false,
+  onClickDelete: () => {},
+  onUpdateDoc: () => {},
+};
+
+Row.propTypes = {
+  currentDocVersion: PropTypes.string,
+  data: PropTypes.object,
+  isHeader: PropTypes.bool,
+  onClickDelete: PropTypes.func,
+  onUpdateDoc: PropTypes.func,
+};
+
+export default Row;

package/admin/src/containers/App/index.js

@@ -0,0 +1,30 @@
+/**
+ *
+ * This component is the skeleton around the actual pages, and should only
+ * contain code that should be seen on all pages. (e.g. navigation bar)
+ *
+ */
+
+import React from 'react';
+import { Switch, Route } from 'react-router-dom';
+import { NotFound, CheckPagePermissions } from 'strapi-helper-plugin';
+// Utils
+import pluginPermissions from '../../permissions';
+import pluginId from '../../pluginId';
+// Containers
+import HomePage from '../HomePage';
+
+function App() {
+  return (
+    <CheckPagePermissions permissions={pluginPermissions.main}>
+      <div className={pluginId}>
+        <Switch>
+          <Route path={`/plugins/${pluginId}`} component={HomePage} exact />
+          <Route component={NotFound} />
+        </Switch>
+      </div>
+    </CheckPagePermissions>
+  );
+}
+
+export default App;

package/admin/src/containers/HomePage/actions.js

@@ -0,0 +1,72 @@
+/*
+ *
+ * HomePage actions
+ *
+ */
+
+import {
+  GET_DOC_INFOS,
+  GET_DOC_INFOS_SUCCEEDED,
+  ON_CHANGE,
+  ON_CLICK_DELETE_DOC,
+  ON_CONFIRM_DELETE_DOC,
+  ON_SUBMIT,
+  ON_UPDATE_DOC,
+  SET_FORM_ERRORS,
+} from './constants';
+
+export function getDocInfos() {
+  return {
+    type: GET_DOC_INFOS,
+  };
+}
+
+export function getDocInfosSucceeded(data) {
+  return {
+    type: GET_DOC_INFOS_SUCCEEDED,
+    data,
+  };
+}
+
+export function onChange({ target }) {
+  return {
+    type: ON_CHANGE,
+    keys: target.name.split('.'),
+    value: target.value,
+  };
+}
+
+export function onClickDeleteDoc(version) {
+  return {
+    type: ON_CLICK_DELETE_DOC,
+    version,
+  };
+}
+
+export function onConfirmDeleteDoc() {
+  return {
+    type: ON_CONFIRM_DELETE_DOC,
+  };
+}
+
+export function onSubmit(e) {
+  e.preventDefault();
+
+  return {
+    type: ON_SUBMIT,
+  };
+}
+
+export function onUpdateDoc(version) {
+  return {
+    type: ON_UPDATE_DOC,
+    version,
+  };
+}
+
+export function setFormErrors(errors) {
+  return {
+    type: SET_FORM_ERRORS,
+    errors,
+  };
+}

package/admin/src/containers/HomePage/components.js

@@ -0,0 +1,59 @@
+import styled from 'styled-components';
+
+const ContainerFluid = styled.div`
+  padding: 18px 30px;
+  > div:first-child {
+    max-height: 33px;
+  }
+
+  .buttonOutline {
+    height: 30px;
+    padding: 0 15px;
+    border: 1px solid #dfe0e1;
+    font-weight: 500;
+    font-size: 13px;
+    &:before {
+      margin-right: 10px;
+      content: '\f08e';
+      font-family: 'FontAwesome';
+      font-size: 10px;
+    }
+  }
+`;
+
+const StyledRow = styled.div`
+  padding-top: 11px;
+  > div:last-child {
+    > div {
+      padding-bottom: 0 !important;
+    }
+  }
+  > div:first-child {
+    > div {
+      margin-bottom: 22px !important;
+    }
+  }
+`;
+
+const VersionWrapper = styled.div`
+  margin-top: -9px;
+  margin-left: -28px;
+  margin-right: -28px;
+  > div:first-child {
+    height: 18px;
+    line-height: 16px;
+    border-bottom: 0;
+
+    > div:nth-child(2) {
+      font-weight: 600;
+      color: #9ea7b8;
+    }
+  }
+  > div:last-child {
+    > div {
+      border-bottom: none;
+    }
+  }
+`;
+
+export { ContainerFluid, StyledRow, VersionWrapper };

package/admin/src/containers/HomePage/constants.js

@@ -0,0 +1,14 @@
+/*
+ *
+ * HomePage constants
+ *
+ */
+
+export const GET_DOC_INFOS = 'documentation/HomePage/GET_DOC_INFOS';
+export const GET_DOC_INFOS_SUCCEEDED = 'documentation/HomePage/GET_DOC_INFOS_SUCCEEDED';
+export const ON_CHANGE = 'documentation/HomePage/ON_CHANGE';
+export const ON_CLICK_DELETE_DOC = 'documentation/HomePage/ON_CLICK_DELETE_DOC';
+export const ON_CONFIRM_DELETE_DOC = 'documentation/HomePage/ON_CONFIRM_DELETE_DOC';
+export const ON_SUBMIT = 'documentation/HomePage/ON_SUBMIT';
+export const ON_UPDATE_DOC = 'documentation/HomePage/ON_UPDATE_DOC';
+export const SET_FORM_ERRORS = 'documentation/HomePage/SET_FORM_ERRORS';