Improve documentation to better guide customers and link to the schemas

3scale · Apr 19, 2023 · 0700720 · 0700720
1 parent c420580
commit 0700720
Show file tree

Hide file tree

Showing 3 changed files with 27 additions and 19 deletions.
diff --git a/doc/active_docs/account_management_api.json b/doc/active_docs/account_management_api.json
@@ -19,8 +19,8 @@
           "Accounts"
         ],
         "requestBody": {
-          "description": "Create Account",
           "required": true,
+          "description": "Custom fields can be specified in the request by adding `&custom-field=value` to the body parameters. See <a href=\"#model-SignupExpressRequest\">SignupExpressRequest</a> schema for the request body definition.",
           "content": {
             "application/x-www-form-urlencoded": {
               "schema": {
@@ -148,6 +148,7 @@
         ],
         "requestBody": {
           "required": true,
+          "description": "Custom fields can be specified in the request by adding `&custom-field=value` to the body parameters. See <a href=\"#model-AccountUpdateRequest\">AccountUpdateRequest</a> schema for the request body definition.",
           "content": {
             "application/x-www-form-urlencoded": {
               "schema": {
@@ -320,6 +321,7 @@
         ],
         "requestBody": {
           "required": true,
+          "description": "Custom fields can be specified in the request by adding `&custom-field=value` to the body parameters. See <a href=\"#model-ApplicationCreateRequest\">ApplicationCreateRequest</a> schema for the request body definition.",
           "content": {
             "application/x-www-form-urlencoded": {
               "schema": {
@@ -411,6 +413,7 @@
         ],
         "requestBody": {
           "required": true,
+          "description": "Custom fields can be specified in the request by adding `&custom-field=value` to the body parameters. See <a href=\"#model-ApplicationUpdateRequest\">ApplicationUpdateRequest</a> schema for the request body definition.",
           "content": {
             "application/x-www-form-urlencoded": {
               "schema": {
@@ -1711,6 +1714,7 @@
         ],
         "requestBody": {
           "required": true,
+          "description": "Custom fields can be specified in the request by adding `&custom-field=value` to the body parameters. See <a href=\"#model-UserCreateRequest\">UserCreateRequest</a> schema for the request body definition.",
           "content": {
             "application/x-www-form-urlencoded": {
               "schema": {
@@ -1802,6 +1806,7 @@
         ],
         "requestBody": {
           "required": true,
+          "description": "Custom fields can be specified in the request by adding `&custom-field=value` to the body parameters. See <a href=\"#model-UserUpdateRequest\">UserUpdateRequest</a> schema for the request body definition.",
           "content": {
             "application/x-www-form-urlencoded": {
               "schema": {
@@ -2197,6 +2202,7 @@
         ],
         "requestBody": {
           "required": true,
+          "description": "Custom fields can be specified in the request by adding `&custom-field=value` to the body parameters. See <a href=\"#model-UserCreateRequest\">UserCreateRequest</a> schema for the request body definition.",
           "content": {
             "application/x-www-form-urlencoded": {
               "schema": {
@@ -2268,6 +2274,7 @@
         ],
         "requestBody": {
           "required": true,
+          "description": "Custom fields can be specified in the request by adding `&custom-field=value` to the body parameters. See <a href=\"#model-UserUpdateRequest\">UserUpdateRequest</a> schema for the request body definition.",
           "content": {
             "application/x-www-form-urlencoded": {
               "schema": {
@@ -7270,6 +7277,7 @@
         ],
         "requestBody": {
           "required": true,
+          "description": "Custom fields can be specified in the request by adding `&custom-field=value` to the body parameters. See <a href=\"#model-ServiceCreateRequest\">ServiceCreateRequest</a> schema for the request body definition.",
           "content": {
             "application/x-www-form-urlencoded": {
               "schema": {
@@ -7341,6 +7349,7 @@
         ],
         "requestBody": {
           "required": true,
+          "description": "Custom fields can be specified in the request by adding `&custom-field=value` to the body parameters. See <a href=\"#model-ServiceUpdateRequest\">ServiceUpdateRequest</a> schema for the request body definition.",
           "content": {
             "application/x-www-form-urlencoded": {
               "schema": {

diff --git a/doc/active_docs/service_management_api.json b/doc/active_docs/service_management_api.json
@@ -80,7 +80,7 @@
           {
             "name": "usage",
             "in": "query",
-            "description": "Predicted Usage. Actual usage will need to be reported with a report or an authrep.",
+            "description": "Predicted Usage. Actual usage will need to be reported with a report or an authrep.\n\nThe usage object (see <a href=\"#model-Usage\">Usage</a> schema for definition) may contain multiple fields, where the keys are metrics' system names, and the values are the reported usage.",
             "schema": {
               "$ref": "#/components/schemas/Usage"
             },
@@ -165,7 +165,7 @@
           {
             "name": "usage",
             "in": "query",
-            "description": "Usage will increment the metrics with the values passed. The value can be only a positive integer (e.g. 1, 50). Reporting usage[hits]=1 will increment the hits counter by +1.",
+            "description": "Usage will increment the metrics with the values passed. The value can be only a positive integer (e.g. 1, 50). Reporting usage[hits]=1 will increment the hits counter by +1.\n\nThe usage object (see <a href=\"#model-Usage\">Usage</a> schema for definition) may contain multiple fields, where the keys are metrics' system names, and the values are the reported usage.",
             "schema": {
               "$ref": "#/components/schemas/Usage"
             },
@@ -177,7 +177,13 @@
             "in": "query",
             "description": "Request Log allows to log status codes of your API back to 3scale to maintain a log of the latest activity on your API. Request Logs are optional and not available in all 3scale plans.",
             "schema": {
-              "$ref": "#/components/schemas/Log"
+              "type": "object",
+              "properties": {
+                "code": {
+                  "type": "string",
+                  "example": 200
+                }
+              }
             },
             "style": "deepObject",
             "explode": true
@@ -249,7 +255,7 @@
           {
             "name": "usage",
             "in": "query",
-            "description": "Predicted usage. Actual usage will need to be reported with a report or an authrep call.",
+            "description": "Predicted usage. Actual usage will need to be reported with a report or an authrep call.\n\nThe usage object (see <a href=\"#model-Usage\">Usage</a> schema for definition) may contain multiple fields, where the keys are metrics' system names, and the values are the reported usage.",
             "schema": {
               "$ref": "#/components/schemas/Usage"
             },
@@ -339,7 +345,7 @@
           {
             "name": "usage",
             "in": "query",
-            "description": "Usage will increment the metrics with the values passed. The value can be only a positive integer (e.g. 1, 50). Reporting usage[hits]=1 will increment the hits counter by +1.",
+            "description": "Usage will increment the metrics with the values passed. The value can be only a positive integer (e.g. 1, 50). Reporting usage[hits]=1 will increment the hits counter by +1.\n\nThe usage object (see <a href=\"#model-Usage\">Usage</a> schema for definition) may contain multiple fields, where the keys are metrics' system names, and the values are the reported usage.",
             "schema": {
               "$ref": "#/components/schemas/Usage"
             },
@@ -449,6 +455,7 @@
       },
       "Transactions": {
         "type": "array",
+        "description": "Array of transaction details (see <a href=\"#model-Transaction\">Transaction</a> definition). All transactions must include either `user_key` or `app_id` (the same for all transactions), depending on the API's authentication pattern. Transactions may optionally include the `timestamp` field.",
         "items": {
           "$ref": "#/components/schemas/Transaction"
         }
@@ -482,15 +489,6 @@
             "hits": 1
           }
         }
-      },
-      "Log": {
-        "type": "object",
-        "properties": {
-          "code": {
-            "type": "string",
-            "example": 200
-          }
-        }
       }
     }
   }

diff --git a/doc/active_docs/service_management_api_on_premises.json b/doc/active_docs/service_management_api_on_premises.json
@@ -80,7 +80,7 @@
           {
             "name": "usage",
             "in": "query",
-            "description": "Predicted Usage. Actual usage will need to be reported with a report or an authrep.",
+            "description": "Predicted Usage. Actual usage will need to be reported with a report or an authrep.\n\nThe usage object (see <a href=\"#model-Usage\">Usage</a> schema for definition) may contain multiple fields, where the keys are metrics' system names, and the values are the reported usage.",
             "schema": {
               "$ref": "#/components/schemas/Usage"
             },
@@ -165,7 +165,7 @@
           {
             "name": "usage",
             "in": "query",
-            "description": "Usage will increment the metrics with the values passed. The value can be only a positive integer (e.g. 1, 50). Reporting usage[hits]=1 will increment the hits counter by +1.",
+            "description": "Usage will increment the metrics with the values passed. The value can be only a positive integer (e.g. 1, 50). Reporting usage[hits]=1 will increment the hits counter by +1.\n\nThe usage object (see <a href=\"#model-Usage\">Usage</a> schema for definition) may contain multiple fields, where the keys are metrics' system names, and the values are the reported usage.",
             "schema": {
               "$ref": "#/components/schemas/Usage"
             },
@@ -239,7 +239,7 @@
           {
             "name": "usage",
             "in": "query",
-            "description": "Predicted usage. Actual usage will need to be reported with a report or an authrep call.",
+            "description": "Predicted usage. Actual usage will need to be reported with a report or an authrep call.\n\nThe usage object (see <a href=\"#model-Usage\">Usage</a> schema for definition) may contain multiple fields, where the keys are metrics' system names, and the values are the reported usage.",
             "schema": {
               "$ref": "#/components/schemas/Usage"
             },
@@ -329,7 +329,7 @@
           {
             "name": "usage",
             "in": "query",
-            "description": "Usage will increment the metrics with the values passed. The value can be only a positive integer (e.g. 1, 50). Reporting usage[hits]=1 will increment the hits counter by +1.",
+            "description": "Usage will increment the metrics with the values passed. The value can be only a positive integer (e.g. 1, 50). Reporting usage[hits]=1 will increment the hits counter by +1.\n\nThe usage object (see <a href=\"#model-Usage\">Usage</a> schema for definition) may contain multiple fields, where the keys are metrics' system names, and the values are the reported usage.",
             "schema": {
               "$ref": "#/components/schemas/Usage"
             },
@@ -429,6 +429,7 @@
       },
       "Transactions": {
         "type": "array",
+        "description": "Array of transaction details (see <a href=\"#model-Transaction\">Transaction</a> definition). All transactions must include either `user_key` or `app_id` (the same for all transactions), depending on the API's authentication pattern. Transactions may optionally include the `timestamp` field.",
         "items": {
           "$ref": "#/components/schemas/Transaction"
         }