Merge pull request #668 from akeneo/API-1867

fix(API-1867): update catalogs doc + update postman api export

Author: samokiss

content/files/Akeneo PIM API.postman_collection.json

@@ -15,7 +15,7 @@
             "header": [
               {
                 "key": "Authorization",
-                "value": "Bearer {{token}}"
+                "value": "Bearer {{appToken}}"
               }
             ],
             "url": {
@@ -42,7 +42,7 @@
             "header": [
               {
                 "key": "Authorization",
-                "value": "Bearer {{token}}"
+                "value": "Bearer {{appToken}}"
               }
             ],
             "url": {
@@ -67,7 +67,7 @@
             "header": [
               {
                 "key": "Authorization",
-                "value": "Bearer {{token}}"
+                "value": "Bearer {{appToken}}"
               },
               {
                 "key": "Content-Type",
@@ -100,7 +100,7 @@
             "header": [
               {
                 "key": "Authorization",
-                "value": "Bearer {{token}}"
+                "value": "Bearer {{appToken}}"
               },
               {
                 "key": "Content-Type",
@@ -134,7 +134,7 @@
             "header": [
               {
                 "key": "Authorization",
-                "value": "Bearer {{token}}"
+                "value": "Bearer {{appToken}}"
               },
               {
                 "key": "Content-Type",
@@ -164,7 +164,7 @@
             "header": [
               {
                 "key": "Authorization",
-                "value": "Bearer {{token}}"
+                "value": "Bearer {{appToken}}"
               }
             ],
             "url": {
@@ -185,7 +185,8 @@
           },
           "response": []
         }
-      ]
+      ],
+      "description": "App catalog\" folder: \"Make sure the variable \"appToken\" is completed before calling the API with Catalog endpoints."
     },
     {
       "name": "Association type (>= v2)",
@@ -5093,4 +5094,4 @@
       }
     }
   ]
-}
+}

content/swagger/akeneo-web-api.json

@@ -6,6 +6,7 @@ get:
     - Catalogs
   x-versions:
     - "SaaS"
+  x-app-token: true
   parameters:
     - $ref: '#/parameters/page'
     - name: limit
@@ -73,6 +74,7 @@ post:
     - Catalogs
   x-versions:
     - "SaaS"
+  x-app-token: true
   description: This endpoint allows you to create a new catalog.
   parameters:
     - name: body

content/swagger/resources/app_catalogs/routes/app_catalogs.yaml

@@ -6,6 +6,7 @@ get:
     - Catalogs
   x-versions:
     - "SaaS"
+  x-app-token: true
   parameters:
     - name: id
       in: path
@@ -31,6 +32,7 @@ patch:
     - Catalogs
   x-versions:
     - "SaaS"
+  x-app-token: true
   description: This endpoint allows you to update a catalog.
   parameters:
     - name: id
@@ -65,6 +67,7 @@ delete:
     - Catalog
   x-versions:
     - "SaaS"
+  x-app-token: true
   description: This endpoint allows you to delete a catalog.
   parameters:
     - name: id

content/swagger/resources/app_catalogs/routes/app_catalogs_id.yaml

@@ -6,6 +6,7 @@ get:
     - Catalog products
   x-versions:
     - "SaaS"
+  x-app-token: true
   parameters:
     - name: id
       in: path

content/swagger/resources/app_catalogs/routes/app_catalogs_id_product_uuids.yaml

@@ -65,6 +65,11 @@
                 {{#each categories as |category categoryId|}}
                     <a class="anchor" id="{{{categoryId}}}"></a>
                     <h1>{{{categoryName}}}{{#if categoryDeprecated}}<em> - Deprecated</em>{{/if}}</h1>
+                    {{#if isAppCategory}}
+                        <div class="alert alert-warning">
+                            <p>Make sure you have a valid App token with scopes related to catalogs authorized in order to use the following endpoints. You can find information about these scopes in the section <a href="/apps/catalogs.html#step-1-ask-for-catalog-scopes">ask for catalog scopes</a></p>
+                        </div>
+                    {{/if}}
                     {{#if categoryDeprecated}}
                         <div class="alert alert-warning">
                             <p>With the introduction of our new way to handle assets, the Asset Manager, the PAM feature will be removed from the v4.0 of the PIM. As a result, from now on, <b>all the endpoints regarding the PAM assets are deprecated</b>. They will not be available anymore starting from the v4.0.<br/>To understand why, we recommend you to read this <a href="https://medium.com/akeneo-labs/between-stability-and-innovation-c2d2dd61a804">Medium post</a>, we wrote on this special occasion.<br/>Also, don't hesitate to take a look at the <a href="/documentation/asset-manager.html">Asset Manager documentation</a> to discover this new feature and how much more efficient it will be to handle your precious assets.</p>
@@ -148,7 +153,11 @@
                                                         <p>
                                                             <code>Authorization</code>
                                                             <a href="#" data-placement="top" data-toggle="tooltip" title="Required header"> <i class="fa fa-asterisk fa-danger"></i> </a>
+                                                        {{#if x-app-token}}
+                                                            <small>&bull; Equal to 'Bearer xxx', 'xxx' being the App authentication token, see <a href="/apps/apps-getting-started.html" target="_blank">documentation for getting an app token</a></small>
+                                                        {{else}}
                                                             <small>&bull; Equal to 'Bearer xxx', `xxx` being the authentication token, see <a href="/documentation/authentication.html">Authentication</a> section</small>
+                                                        {{/if}}
                                                         </p>
                                                     {{/unless}}
                                                     {{#if x-body-by-line}}

src/api-reference/reference.handlebars

@@ -137,6 +137,9 @@ gulp.task('reference', ['clean-dist', 'less'], function() {
                             if (!data.categories[escapeCategory].resources[escapeTag]) {
                                 data.categories[escapeCategory].resources[escapeTag] = { resourceName: operation.tags[0], operations: {}};
                             }
+                            if(category.includes('Catalogs for Apps')) {
+                                data.categories[escapeCategory].isAppCategory = true;
+                            }
                             data.categories[escapeCategory].resources[escapeTag].operations[operation.operationId] = _.extend(operation, {
                                 verb: verb,
                                 path: pathUri
@@ -182,6 +185,9 @@ gulp.task('reference', ['clean-dist', 'less'], function() {
                             if (!data.categories[escapeCategory].resources[escapeTag]) {
                                 data.categories[escapeCategory].resources[escapeTag] = { resourceName: operation.tags[0], operations: {}};
                             }
+                            if(category.includes('Catalogs for Apps')) {
+                                data.categories[escapeCategory].isAppCategory = true;
+                            }
                             var groupedParameters = _.groupBy(operation.parameters, function(parameter) {
                                 return parameter.in;
                             });