Update openapi.json spec with responses for /access/

We now have two different possible 200 responses for `/access/`, one with pagination, and one without. OpenAPI 3 supports the use of `anyOf` and `oneOf` for response body schemas [1]. This updates the spec to reflect those possible responses (with and without pagination), and includes examples of each. [1] https://swagger.io/docs/specification/describing-responses/
RedHatInsights · Feb 4, 2020 · 199c1fb · 199c1fb
1 parent 2389fef
commit 199c1fb
Showing 1 changed file with 80 additions and 3 deletions.
diff --git a/docs/source/specs/openapi.json b/docs/source/specs/openapi.json
@@ -1417,19 +1417,34 @@
             }
           },
           {
-            "$ref": "#/components/parameters/QueryLimit"
+            "$ref": "#/components/parameters/QueryLimitNoDefault"
           },
           {
             "$ref": "#/components/parameters/QueryOffset"
           }
         ],
         "responses": {
           "200": {
-            "description": "A paginated list of access objects",
+            "description": "A list of access objects. By default, this request will not be paginated. To received a paginated response, include the `/?limit=` query parameter.",
             "content": {
               "application/json": {
                 "schema": {
-                  "$ref": "#/components/schemas/AccessPagination"
+                  "oneOf": [
+                    {
+                      "$ref": "#/components/schemas/AccessNoPagination"
+                    },
+                    {
+                      "$ref": "#/components/schemas/AccessPagination"
+                    }
+                  ]
+                },
+                "examples": {
+                  "AccessNoPagination": {
+                    "$ref": "#/components/examples/AccessNoPagination"
+                  },
+                  "AccessPagination": {
+                    "$ref": "#/components/examples/AccessPagination"
+                  }
                 }
               }
             }
@@ -1491,6 +1506,17 @@
           "maximum": 1000
         }
       },
+      "QueryLimitNoDefault": {
+        "in": "query",
+        "name": "limit",
+        "required": false,
+        "description": "Parameter for selecting the amount of data returned.",
+        "schema": {
+          "type": "integer",
+          "minimum": 1,
+          "maximum": 1000
+        }
+      },
       "NameFilter": {
         "in": "query",
         "name": "name",
@@ -2214,6 +2240,24 @@
           }
         ]
       },
+      "AccessNoPagination": {
+        "allOf": [
+          {
+            "type": "object",
+            "required": [
+              "data"
+            ],
+            "properties": {
+              "data": {
+                "type": "array",
+                "items": {
+                  "$ref": "#/components/schemas/Access"
+                }
+              }
+            }
+          }
+        ]
+      },
       "Status": {
         "required": [
           "api_version"
@@ -2265,6 +2309,39 @@
           }
         }
       }
+    },
+    "examples": {
+      "AccessNoPagination": {
+        "value": {
+          "data": [
+            {
+              "permission": "app-name:*:*",
+              "resourceDefinitions": []
+            }
+          ]
+        }
+      },
+      "AccessPagination": {
+        "value": {
+          "meta": {
+            "count": 1,
+            "limit": 10,
+            "offset": 0
+          },
+          "links": {
+            "first": "/access/?application=app-name&limit=10",
+            "next": null,
+            "previous": null,
+            "last": "/access/?application=app-name&limit=10"
+          },
+          "data": [
+            {
+              "permission": "app-name:*:*",
+              "resourceDefinitions": []
+            }
+          ]
+        }
+      }
     }
   }
 }