Improve doc merge and start documentation of U&P

2025-12-24 21:54:24 +00:00 · 2022-06-02 10:22:20 +02:00 · 2022-06-02 10:22:20 +02:00 · 573d56bc30
commit 573d56bc30
parent bdf2e13290
7 changed files with 348 additions and 53 deletions
--- a/examples/getstarted/content-api.json
+++ b/examples/getstarted/content-api.json
@ -0,0 +1,52 @@
+Usage:
+  yq eval [expression] [yaml_file1]... [flags]
+
+Aliases:
+  eval, e
+
+Examples:
+
+# Reads field under the given path for each file
+yq e '.a.b' f1.yml f2.yml 
+
+# Prints out the file
+yq e sample.yaml 
+
+# Pipe from STDIN
+## use '-' as a filename to pipe from STDIN
+cat file2.yml | yq e '.a.b' file1.yml - file3.yml
+
+# Creates a new yaml document
+## Note that editing an empty file does not work.
+yq e -n '.a.b.c = "cat"' 
+
+# Update a file inplace
+yq e '.a.b = "cool"' -i file.yaml 
+
+
+Flags:
+  -h, --help   help for eval
+
+Global Flags:
+  -C, --colors                        force print with colors
+  -e, --exit-status                   set exit status if there are no matches or null or false is returned
+      --expression string             forcibly set the expression argument. Useful when yq argument detection thinks your expression is a file.
+      --from-file string              Load expression from specified file.
+  -f, --front-matter string           (extract|process) first input as yaml front-matter. Extract will pull out the yaml content, process will run the expression against the yaml content, leaving the remaining data intact
+      --header-preprocess             Slurp any header comments and separators before processing expression. (default true)
+  -I, --indent int                    sets indent level for output (default 2)
+  -i, --inplace                       update the file inplace of first file given.
+  -p, --input-format string           [yaml|y|props|p|xml|x] parse format for input. Note that json is a subset of yaml. (default "yaml")
+  -M, --no-colors                     force print with no colors
+  -N, --no-doc                        Don't print document separators (---)
+  -n, --null-input                    Don't read input, simply evaluate the expression given. Useful for creating docs from scratch.
+  -o, --output-format string          [yaml|y|json|j|props|p|xml|x] output format type. (default "yaml")
+  -P, --prettyPrint                   pretty print, shorthand for '... style = ""'
+  -s, --split-exp string              print each result (or doc) into a file named (exp). [exp] argument must return a string. You can use $index in the expression as the result counter.
+      --split-exp-file string         Use a file to specify the split-exp expression.
+      --unwrapScalar                  unwrap scalar, print the value with no quotes, colors or comments (default true)
+  -v, --verbose                       verbose mode
+      --xml-attribute-prefix string   prefix for xml attributes (default "+")
+      --xml-content-name string       name for xml content (if no attribute name is present). (default "+content")
+      --xml-strict-mode               enables strict parsing of XML. See https://pkg.go.dev/encoding/xml for more details.
+
--- a/packages/plugins/documentation/package.json
+++ b/packages/plugins/documentation/package.json
@ -42,7 +42,8 @@
    "react-router-dom": "5.2.0",
    "redux": "^4.0.1",
    "reselect": "^4.0.0",
-    "swagger-ui-dist": "3.47.1"
+    "swagger-ui-dist": "3.47.1",
+    "yaml": "2.1.1"
  },
  "peerDependencies": {
    "@strapi/strapi": "^4.0.0"
--- a/packages/plugins/documentation/server/services/documentation.js
+++ b/packages/plugins/documentation/server/services/documentation.js
@ -15,6 +15,11 @@ module.exports = ({ strapi }) => {

  return {
    registerDoc(doc) {
+      // parseYaml
+      if (typeof doc === 'string') {
+        doc = require('yaml').parse(doc);
+      }
+      // receive an object we can register it directly
      registeredDocs.push(doc);
    },
    getDocumentationVersion() {
@ -32,7 +37,7 @@ module.exports = ({ strapi }) => {
    getDocumentationVersions() {
      return fs
        .readdirSync(this.getFullDocumentationPath())
-        .map(version => {
+        .map((version) => {
          try {
            const doc = JSON.parse(
              fs.readFileSync(
@ -46,7 +51,7 @@ module.exports = ({ strapi }) => {
            return null;
          }
        })
-        .filter(x => x);
+        .filter((x) => x);
    },

    /**
@ -93,7 +98,7 @@ module.exports = ({ strapi }) => {

    getPluginAndApiInfo() {
      const plugins = _.get(config, 'x-strapi-config.plugins');
-      const pluginsToDocument = plugins.map(plugin => {
+      const pluginsToDocument = plugins.map((plugin) => {
        return {
          name: plugin,
          getter: 'plugin',
@ -101,7 +106,7 @@ module.exports = ({ strapi }) => {
        };
      });

-      const apisToDocument = Object.keys(strapi.api).map(api => {
+      const apisToDocument = Object.keys(strapi.api).map((api) => {
        return {
          name: api,
          getter: 'api',
@ -180,9 +185,21 @@ module.exports = ({ strapi }) => {

      const finalDoc = { ...config, paths };

-      registeredDocs.forEach(doc => {
+      registeredDocs.forEach((doc) => {
+        // Add tags
+        finalDoc.tags = finalDoc.tags || [];
+        finalDoc.tags.push(...(doc.tags || []));
+
+        // Add Paths
        _.assign(finalDoc.paths, doc.paths);
-        _.assign(finalDoc.components, doc.components);
+
+        // Add components
+        _.forEach(doc.components || {}, (val, key) => {
+          finalDoc.components[key] = finalDoc.components[key] || {};
+
+          console.log(key);
+          _.assign(finalDoc.components[key], val);
+        });
      });

      console.log(finalDoc);
--- a/packages/plugins/users-permissions/documentation/content-api.json
+++ b/packages/plugins/users-permissions/documentation/content-api.json
@ -1,36 +0,0 @@
-{
-  "paths": {
-    "/connect/(.*)": {
-      "get": {
-        "tags": ["Users & Permissions - Auth"],
-        "description": "Connect with a provider",
-        "responses": {
-          "301": {
-            "description": "Redirect to provider auth"
-          }
-        }
-      }
-    },
-    "/auth/local": {
-      "post": {
-        "tags": ["Users & Permissions - Auth"],
-        "description": "Connect locally",
-        "responses": {
-          "200": {
-            "description": "Connection"
-          }
-        }
-      }
-    },
-    "/auth/local/register": {
-      "post": {
-        "tags": ["Users & Permissions - Auth"],
-        "responses": {
-          "200": {
-            "description": "User registered"
-          }
-        }
-      }
-    }
-  }
-}
--- a/packages/plugins/users-permissions/documentation/content-api.yaml
+++ b/packages/plugins/users-permissions/documentation/content-api.yaml
@ -1,48 +1,300 @@
+tags:
+  - name: 'Users-Permissions - Auth'
+    description: 'Authentication endpoints'
+    externalDocs:
+      description: 'Find out more'
+      url: 'https://docs.strapi.io/developer-docs/latest/plugins/users-permissions.html'
+
+  - name: 'Users-Permissions - Users & Roles'
+    description: 'Users, roles, and permissions endpoints'
+    externalDocs:
+      description: 'Find out more'
+      url: 'https://docs.strapi.io/developer-docs/latest/plugins/users-permissions.html'
+
 paths:
  '/connect/(.*)':
    get:
-      description: Connect with a provider
+      tags:
+        - Users-Permissions - Auth
+      summary: Login with a provider
+      description: Redirects to provider login before being redirect to /auth/{provider}/callback
      responses:
        301:
-          description: Redirect to provider auth
+          description: Redirect response
+        default:
+          description: Error
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Error'
  /auth/local:
    post:
-      description: Connect locally
+      tags:
+        - Users-Permissions - Auth
+      summary: Local login
+      description: Returns a jwt token and user info
+      requestBody:
+        content:
+          application/json:
+            schema:
+              type: object
+              properties:
+                identifier:
+                  type: string
+                password:
+                  type: string
+            example:
+              identier: foobar
+              password: Test1234
+        required: true
      responses:
        200:
          description: Connection
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Users-Permissions-UserRegistration'
+        default:
+          description: Error
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Error'
  /auth/local/register:
    post:
+      tags:
+        - Users-Permissions - Auth
+      summary: Register a user
+      description: Returns a jwt token and user info
+      requestBody:
+        content:
+          application/json:
+            schema:
+              type: object
+              properties:
+                username:
+                  type: string
+                email:
+                  type: string
+                password:
+                  type: string
+            example:
+              username: foobar
+              email: foo.bar@strapi.io
+              password: Test1234
+        required: true
      responses:
        200:
-          description: User registered
-  /auth/forgot-password:
+          description: Successfull registration
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Users-Permissions-UserRegistration'
+        default:
+          description: Error
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Error'

+  /auth/{provider}/callback:
+    get:
+      tags:
+        - Users-Permissions - Auth
+      summary: Default Callback from provider auth
+      responses:
+        200:
+          description: Returns a jwt token and user info
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Users-Permissions-UserRegistration'
+        default:
+          description: Error
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Error'
+
+  /auth/forgot-password:
+    post:
+      tags:
+        - Users-Permissions - Auth
+      summary: Send rest password email
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              type: object
+              properties:
+                email:
+                  type: string
+            example:
+              email: foo.bar@strapi.io
+      responses:
+        200:
+          description: Returns ok
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  ok:
+                    type: enum
+                    enum: [true]
  /auth/reset-password:
+    post:
+      tags:
+        - Users-Permissions - Auth
+      summary: Rest user password
+      responses:
+        default:
+          description: 'Success'
  /auth/email-confirmation:
+    get:
+      tags:
+        - Users-Permissions - Auth
+      summary: Confirm user email
+      responses:
+        default:
+          description: 'Success'
  /auth/send-email-confirmation:
+    post:
+      tags:
+        - Users-Permissions - Auth
+      summary: Send confirmation email
+      responses:
+        default:
+          description: 'Success'

  /users-permissions/permissions:
    get:
+      tags:
+        - Users-Permissions - Users & Roles
+      responses:
+        default:
+          description: 'Success'
  /users-permissions/roles:
    get:
+      tags:
+        - Users-Permissions - Users & Roles
+      responses:
+        default:
+          description: 'Success'
    post:
-  /users-permissions/roles{id}:
+      tags:
+        - Users-Permissions - Users & Roles
+      responses:
+        default:
+          description: 'Success'
+  /users-permissions/roles/{id}:
    get:
+      tags:
+        - Users-Permissions - Users & Roles
+      responses:
+        default:
+          description: 'Success'
+  /users-permissions/roles/{role}:
    put:
+      tags:
+        - Users-Permissions - Users & Roles
+      responses:
+        default:
+          description: 'Success'
    delete:
+      tags:
+        - Users-Permissions - Users & Roles
+      responses:
+        default:
+          description: 'Success'

  /users:
    get:
+      tags:
+        - Users-Permissions - Users & Roles
+      responses:
+        default:
+          description: 'Success'
    post:
+      tags:
+        - Users-Permissions - Users & Roles
+      responses:
+        default:
+          description: 'Success'
  /users/{id}:
    get:
+      tags:
+        - Users-Permissions - Users & Roles
+      responses:
+        default:
+          description: 'Success'
    put:
+      tags:
+        - Users-Permissions - Users & Roles
+      responses:
+        default:
+          description: 'Success'
    delete:
+      tags:
+        - Users-Permissions - Users & Roles
+      responses:
+        204:
+          description: Successfull deletion
  /users/me:
+    get:
+      tags:
+        - Users-Permissions - Users & Roles
+      responses:
+        default:
+          description: 'Success'
  /users/count:
+    get:
+      tags:
+        - Users-Permissions - Users & Roles
+      responses:
+        default:
+          description: 'Success'

 components:
  schemas:
+    # TODO: generate dynamically from the CT at startup
+    Users-Permissions-User:
+      type: object
+      properties:
+        id:
+          type: integer
+          example: 1
+        username:
+          type: string
+          example: 'foo.bar'
+        email:
+          type: string
+          example: 'foo.bar@strapi.io'
+        provider:
+          type: string
+          example: 'local'
+        confirmed:
+          type: boolean
+          example: true
+        blocked:
+          type: boolean
+          example: false
+        createdAt:
+          type: datetime
+          example: '2022-06-02T08:32:06.258Z'
+        updatedAt:
+          type: datetime
+          example: '2022-06-02T08:32:06.267Z'
+
+    Users-Permissions-UserRegistration:
+      type: object
+      properties:
+        jwt:
+          type: string
+          example: 'eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c'
+        user:
+          $ref: '#/components/schemas/Users-Permissions-User'
+
  parameters:
  responses:
--- a/packages/plugins/users-permissions/server/register.js
+++ b/packages/plugins/users-permissions/server/register.js
@ -1,4 +1,6 @@
 'use strict';
+const fs = require('fs');
+const path = require('path');

 const authStrategy = require('./strategies/users-permissions');
 const sanitizers = require('./utils/sanitize/sanitizers');
@ -12,9 +14,9 @@ module.exports = ({ strapi }) => {
  }

  if (strapi.plugin('documentation')) {
-    strapi
-      .plugin('documentation')
-      .service('documentation')
-      .registerDoc(require('../documentation/content-api'));
+    const specPath = path.join(__dirname, '../documentation/content-api.yaml');
+    const spec = fs.readFileSync(specPath, 'utf8');
+
+    strapi.plugin('documentation').service('documentation').registerDoc(spec);
  }
 };
--- a/yarn.lock
+++ b/yarn.lock
@ -18393,6 +18393,8 @@ path-case@^2.1.0:
  version "2.1.1"
  resolved "https://registry.yarnpkg.com/path-case/-/path-case-2.1.1.tgz#94b8037c372d3fe2906e465bb45e25d226e8eea5"
  integrity sha1-lLgDfDctP+KQbkZbtF4l0ibo7qU=
+  dependencies:
+    no-case "^2.2.0"

 path-dirname@^1.0.0:
  version "1.0.2"
@ -24073,6 +24075,11 @@ yallist@^3.0.0, yallist@^3.0.2, yallist@^3.1.1:
  resolved "https://registry.yarnpkg.com/yallist/-/yallist-3.1.1.tgz#dbb7daf9bfd8bac9ab45ebf602b8cbad0d5d08fd"
  integrity sha512-a4UGQaWPH59mOXUYnAG2ewncQS4i4F43Tv3JoAM+s2VDAmS9NsK8GpDMLrCHPksFT7h3K6TOoUNn2pb7RoXx4g==

+yaml@2.1.1:
+  version "2.1.1"
+  resolved "https://registry.yarnpkg.com/yaml/-/yaml-2.1.1.tgz#1e06fb4ca46e60d9da07e4f786ea370ed3c3cfec"
+  integrity sha512-o96x3OPo8GjWeSLF+wOAbrPfhFOGY0W00GNaxCDv+9hkcDJEnev1yh8S7pgHF0ik6zc8sQLuL8hjHjJULZp8bw==
+
 yaml@^1.10.0, yaml@^1.7.2:
  version "1.10.2"
  resolved "https://registry.yarnpkg.com/yaml/-/yaml-1.10.2.tgz#2301c5ffbf12b467de8da2333a459e29e7920e4b"