Update POST /collections OpenAPI documentation to match the API (add …

…title and properties)
jjrom · Apr 19, 2024 · a57e0b1 · a57e0b1
1 parent 9290526
commit a57e0b1
Show file tree

Hide file tree

Showing 3 changed files with 63 additions and 39 deletions.
diff --git a/app/resto/core/RestoCollection.php b/app/resto/core/RestoCollection.php
@@ -25,13 +25,18 @@
  *
  *  @OA\Schema(
  *      schema="InputCollection",
- *      required={"id"},
+ *      required={"id", "description"},
  *      @OA\Property(
  *          property="id",
  *          type="string",
  *          description="Collection identifier. It must be an unique alphanumeric string containing only [a-zA-Z0-9\-_]."
  *      ),
  *      @OA\Property(
+ *          property="title",
+ *          type="string",
+ *          description="A short descriptive one-line title for the Collection."
+ *      ),
+ *      @OA\Property(
  *          property="description",
  *          type="string",
  *          description="Detailed multi-line description to fully explain the Collection. CommonMark 0.29 syntax MAY be used for rich text representation."
@@ -119,6 +124,11 @@
  *          @OA\Items(ref="#/components/schemas/Provider")
  *      ),
  *      @OA\Property(
+ *          property="properties",
+ *          type="object",
+ *          @OA\JsonContent()
+ *      ),
+ *      @OA\Property(
  *          property="summaries",
  *          type="object",
  *          @OA\JsonContent()
@@ -344,6 +354,12 @@
  *          @OA\Items(ref="#/components/schemas/Provider")
  *      ),
  *      @OA\Property(
+ *          property="properties",
+ *          type="object",
+ *          description="Free properties object",
+ *          @OA\JsonContent()
+ *      ),
+ *      @OA\Property(
  *          property="summaries",
  *          type="object",
  *          @OA\JsonContent(

diff --git a/docs/api/resto-api.html b/docs/api/resto-api.html
@@ -1496,7 +1496,7 @@
 	  	<ul class="toc-list-h1">
 
           <li>
-            <a href="#welcome-to-resto" class="toc-h1 toc-link" data-title="Welcome to resto v8.0.7">Welcome to resto v8.0.7</a>
+            <a href="#welcome-to-resto" class="toc-h1 toc-link" data-title="Welcome to resto v8.0.9">Welcome to resto v8.0.9</a>
 
           </li>
 
@@ -1951,7 +1951,7 @@
     <div class="page-wrapper">
       <div class="dark-box"></div>
       <div class="content">
-        <h1 id="welcome-to-resto">Welcome to resto v8.0.7</h1>
+        <h1 id="welcome-to-resto">Welcome to resto v8.0.9</h1>
 <blockquote>
 <p>Scroll down for code samples, example requests and responses. Select a language for code samples from the tabs above or the mobile navigation menu.</p>
 </blockquote>
@@ -2005,13 +2005,6 @@ <h3 id="collectionsapi--getcollections-parameters">Parameters</h3>
 </thead>
 <tbody>
 <tr>
-<td>_stats</td>
-<td>query</td>
-<td>boolean</td>
-<td>false</td>
-<td>Set to get individual statistics for all collection</td>
-</tr>
-<tr>
 <td>ck</td>
 <td>query</td>
 <td>string</td>
@@ -2375,6 +2368,13 @@ <h3 id="collectionsapi--getcollections-responseschema">Response Schema</h3>
 <td>Homepage on which the provider describes the dataset and publishes contact information.</td>
 </tr>
 <tr>
+<td>»» properties</td>
+<td>object</td>
+<td>false</td>
+<td>none</td>
+<td>Free properties object</td>
+</tr>
+<tr>
 <td>»» summaries</td>
 <td>object</td>
 <td>false</td>
@@ -2720,13 +2720,6 @@ <h3 id="collectionsapi--getcollection-parameters">Parameters</h3>
 <td>true</td>
 <td>Collection identifier</td>
 </tr>
-<tr>
-<td>_stats</td>
-<td>query</td>
-<td>boolean</td>
-<td>false</td>
-<td>True to return full statistics in summaries property. Default is <em>false</em></td>
-</tr>
 </tbody>
 </table>
 <blockquote>
@@ -10046,10 +10039,17 @@ <h3 id="properties">Properties</h3>
 <td>Collection identifier. It must be an unique alphanumeric string containing only [a-zA-Z0-9-_].</td>
 </tr>
 <tr>
-<td>description</td>
+<td>title</td>
 <td>string</td>
 <td>false</td>
 <td>none</td>
+<td>A short descriptive one-line title for the Collection.</td>
+</tr>
+<tr>
+<td>description</td>
+<td>string</td>
+<td>true</td>
+<td>none</td>
 <td>Detailed multi-line description to fully explain the Collection. CommonMark 0.29 syntax MAY be used for rich text representation.</td>
 </tr>
 <tr>
@@ -10158,6 +10158,13 @@ <h3 id="properties">Properties</h3>
 <td>A list of providers, which may include all organizations capturing or processing the data or the hosting provider. Providers should be listed in chronological order with the most recent provider being the last element of the list</td>
 </tr>
 <tr>
+<td>properties</td>
+<td>object</td>
+<td>false</td>
+<td>none</td>
+<td>resto collection</td>
+</tr>
+<tr>
 <td>summaries</td>
 <td>object</td>
 <td>false</td>
@@ -10459,6 +10466,13 @@ <h3 id="properties">Properties</h3>
 <td>A list of providers, which may include all organizations capturing or processing the data or the hosting provider. Providers should be listed in chronological order with the most recent provider being the last element of the list</td>
 </tr>
 <tr>
+<td>properties</td>
+<td>object</td>
+<td>false</td>
+<td>none</td>
+<td>Free properties object</td>
+</tr>
+<tr>
 <td>summaries</td>
 <td>object</td>
 <td>false</td>

diff --git a/docs/api/resto-api.json b/docs/api/resto-api.json
@@ -6,7 +6,7 @@
         "contact": {
             "email": "jerome.gasperi@gmail.com"
         },
-        "version": "8.0.7"
+        "version": "8.0.9"
     },
     "servers": [
         {
@@ -1259,16 +1259,6 @@
                 "description": "Returns a list of all collection descriptions including statistics (i.e. number of products, etc.)",
                 "operationId": "CollectionsAPI::getCollections",
                 "parameters": [
-                    {
-                        "name": "_stats",
-                        "in": "query",
-                        "description": "Set to get individual statistics for all collection",
-                        "required": false,
-                        "style": "form",
-                        "schema": {
-                            "type": "boolean"
-                        }
-                    },
                     {
                         "name": "ck",
                         "in": "query",
@@ -1564,15 +1554,6 @@
                         "schema": {
                             "type": "string"
                         }
-                    },
-                    {
-                        "name": "_stats",
-                        "in": "query",
-                        "description": "True to return full statistics in summaries property. Default is *false*",
-                        "style": "form",
-                        "schema": {
-                            "type": "boolean"
-                        }
                     }
                 ],
                 "responses": {
@@ -4430,13 +4411,18 @@
         "schemas": {
             "InputCollection": {
                 "required": [
-                    "id"
+                    "id",
+                    "description"
                 ],
                 "properties": {
                     "id": {
                         "description": "Collection identifier. It must be an unique alphanumeric string containing only [a-zA-Z0-9\\-_].",
                         "type": "string"
                     },
+                    "title": {
+                        "description": "A short descriptive one-line title for the Collection.",
+                        "type": "string"
+                    },
                     "description": {
                         "description": "Detailed multi-line description to fully explain the Collection. CommonMark 0.29 syntax MAY be used for rich text representation.",
                         "type": "string"
@@ -4526,6 +4512,10 @@
                             "$ref": "#/components/schemas/Provider"
                         }
                     },
+                    "properties": {
+                        "description": "resto collection",
+                        "type": "object"
+                    },
                     "summaries": {
                         "description": "resto collection",
                         "type": "object"
@@ -4734,6 +4724,10 @@
                             "$ref": "#/components/schemas/Provider"
                         }
                     },
+                    "properties": {
+                        "description": "Free properties object",
+                        "type": "object"
+                    },
                     "summaries": {
                         "description": "resto collection",
                         "type": "object"