[ACS-5839] improved documentation and TypeScript support (#1636)

* improved discovery api docs * update doc templates * prefer const * cleanup SearchApi * cleanup api * cleanup GS api * cleanup GS api * cleanup GS api * cleanup Nodes api * improved typings and api
Alfresco · Aug 23, 2023 · 877bae3 · 877bae3
1 parent 241a47e
commit 877bae3
Show file tree

Hide file tree

Showing 48 changed files with 1,281 additions and 2,309 deletions.
diff --git a/api-codegen/src/main/resources/api-code-gen/api_doc.mustache b/api-codegen/src/main/resources/api-code-gen/api_doc.mustache
@@ -3,10 +3,10 @@
 
 All URIs are relative to *{{basePath}}*
 
-Method | HTTP request | Description
-------------- | ------------- | -------------
-{{#operations}}{{#operation}}[**{{operationId}}**]({{classname}}.md#{{operationId}}) | **{{httpMethod}}** {{path}} | {{#summary}}{{&summary}}{{/summary}}
-{{/operation}}{{/operations}}
+| Method | HTTP request | Description |
+| ------------- | ------------- | ------------- |
+| {{#operations}}{{#operation}}[{{operationId}}]({{classname}}.md#{{operationId}}) | **{{httpMethod}}** {{path}} | {{#summary}}{{&summary}}{{/summary}}
+{{/operation}}{{/operations}} |
 
 {{#operations}}
 {{#operation}}
@@ -18,7 +18,7 @@ Method | HTTP request | Description
 
 {{&notes}}{{/notes}}
 
-### Example
+**Example**
 
 ```javascript
 import { AlfrescoApi, {{classname}}} from '@alfresco/js-api';
@@ -37,17 +37,17 @@ const opts = { {{#allParams}}{{^required}}
 
 {{instanceClassname}}.{{{operationId}}}({{#allParams}}{{#required}}{{{paramName}}}{{#vendorExtensions.x-codegen-hasMoreRequired}}, {{/vendorExtensions.x-codegen-hasMoreRequired}}{{/required}}{{/allParams}}{{#hasOptionalParams}}{{#vendorExtensions.x-codegen-hasRequiredParams}}, {{/vendorExtensions.x-codegen-hasRequiredParams}}opts{{/hasOptionalParams}}).then(({{#returnType}}data{{/returnType}}) => {
   {{#returnType}}console.log('API called successfully. Returned data: ' + data);{{/returnType}}{{^returnType}}console.log('API called successfully.');{{/returnType}}
-}, function(error) {
+}, (error) => {
   console.error(error);
 });
 ```
 
 ### Parameters
 {{^allParams}}This endpoint does not need any parameter.{{/allParams}}{{#allParams}}{{#-last}}
-Name | Type | Description  | Notes
-------------- | ------------- | ------------- | -------------{{/-last}}{{/allParams}}
-{{#allParams}} **{{&paramName}}** | {{#isPrimitiveType}}**{{&dataType}}**{{/isPrimitiveType}}{{^isPrimitiveType}}{{#isFile}}**{{&dataType}}**{{/isFile}}{{^isFile}}[**{{&dataType}}**]({{&baseType}}.md){{/isFile}}{{/isPrimitiveType}}| {{&description}} | {{^required}}[optional] {{/required}}{{#defaultValue}}[default to {{defaultValue}}]{{/defaultValue}}
-{{/allParams}}
+| Name | Type | Description  | Notes |
+| ------------- | ------------- | ------------- | -------------{{/-last}}{{/allParams}} |
+| {{#allParams}} **{{&paramName}}** | {{#isPrimitiveType}}**{{&dataType}}**{{/isPrimitiveType}}{{^isPrimitiveType}}{{#isFile}}**{{&dataType}}**{{/isFile}}{{^isFile}}[**{{&dataType}}**]({{&baseType}}.md){{/isFile}}{{/isPrimitiveType}}| {{&description}} | {{^required}}[optional] {{/required}}{{#defaultValue}}[default to {{defaultValue}}]{{/defaultValue}}
+{{/allParams}} |
 
 ### Return type
 

diff --git a/api-codegen/src/main/resources/api-code-gen/model_doc.mustache b/api-codegen/src/main/resources/api-code-gen/model_doc.mustache
@@ -8,11 +8,11 @@
 {{/isEnum}}{{^isEnum}}# {{classname}}
 
 ## Properties
-Name | Type | Description | Notes
------------- | ------------- | ------------- | -------------
-{{#vars}}**{{name}}** | {{#isPrimitiveType}}**{{&datatype}}{{#isListContainer}}[]{{/isListContainer}}**{{/isPrimitiveType}}{{^isPrimitiveType}}[**{{&datatype}}{{#isListContainer}}[]{{/isListContainer}}**]({{complexType}}.md){{/isPrimitiveType}} | {{&description}} | {{^required}}[optional] {{/required}}{{#readOnly}}[readonly] {{/readOnly}}{{#defaultValue}}[default to {{defaultValue}}]{{/defaultValue}}
+| Name | Type | Description | Notes |
+| ------------ | ------------- | ------------- | ------------- |
+| {{#vars}}{{name}} | {{#isPrimitiveType}}{{&datatype}}{{#isListContainer}}[]{{/isListContainer}}{{/isPrimitiveType}}{{^isPrimitiveType}}[**{{&datatype}}{{#isListContainer}}[]{{/isListContainer}}**]({{complexType}}.md){{/isPrimitiveType}} | {{&description}} | {{^required}}[optional] {{/required}}{{#readOnly}}[readonly] {{/readOnly}}{{#defaultValue}}[default to {{defaultValue}}]{{/defaultValue}}
 {{/vars}}
-{{#vars}}{{#isEnum}}
+{{#vars}}{{#isEnum}} |
 
 <a name="{{{datatypeWithEnum}}}"></a>
 ## Enum: {{datatypeWithEnum}}

diff --git a/api-codegen/src/main/resources/api-code-gen/readmeIndex.mustache b/api-codegen/src/main/resources/api-code-gen/readmeIndex.mustache
@@ -9,10 +9,11 @@ All URIs are relative to:
 {{basePath}}
 ```
 
-Class | Method | HTTP request | Description
------------- | ------------- | ------------- | -------------
-{{#apiInfo}}{{#apis}}{{#operations}}{{#operation}}{{classname}} | [**{{operationId}}**](docs/{{classname}}.md#{{operationId}}) | **{{httpMethod}}** {{path}} | {{#summary}}{{&summary}}{{/summary}}
-{{/operation}}{{/operations}}{{/apis}}{{/apiInfo}}
+| Class | Method | HTTP request | Description |
+| ------------ | ------------- | ------------- | ------------- |
+| {{#apiInfo}}{{#apis}}{{#operations}}{{#operation}}{{classname}} | [**{{operationId}}**](docs/{{classname}}.md#{{operationId}}) | **{{httpMethod}}** {{path}} | {{#summary}}{{&summary}}{{/summary}}
+{{/operation}}{{/operations}}{{/apis}}{{/apiInfo}} |
+
 ## Models
 
 {{#models}}{{#model}}- [{{classname}}](docs/{{classname}}.md)

diff --git a/src/api/activiti-rest-api/api/users.api.ts b/src/api/activiti-rest-api/api/users.api.ts
@@ -40,28 +40,15 @@ export class UsersApi extends BaseApi {
         throwIfNotDefined(userId, 'userId');
         throwIfNotDefined(actionRequest, 'actionRequest');
 
-        let postBody = actionRequest;
-
-        let pathParams = {
-            'userId': userId
-        };
-
-        let queryParams = {
+        const pathParams = {
+            userId
         };
 
-        let headerParams = {
-
-        };
-        let formParams = {
-        };
-
-        let contentTypes = ['application/json'];
-        let accepts = ['application/json'];
-
-        return this.apiClient.callApi(
-            '/api/enterprise/users/{userId}', 'POST',
-            pathParams, queryParams, headerParams, formParams, postBody,
-            contentTypes, accepts);
+        return this.post({
+            path: '/api/enterprise/users/{userId}',
+            pathParams,
+            bodyParam: actionRequest
+        });
     }
     /**
         * Stream user profile picture
@@ -86,28 +73,15 @@ export class UsersApi extends BaseApi {
     getUser(userId: number): Promise<UserRepresentation> {
         throwIfNotDefined(userId, 'userId');
 
-        let postBody = null;
-
-        let pathParams = {
-            'userId': userId
-        };
-
-        let queryParams = {
+        const pathParams = {
+            userId
         };
 
-        let headerParams = {
-
-        };
-        let formParams = {
-        };
-
-        let contentTypes = ['application/json'];
-        let accepts = ['application/json'];
-
-        return this.apiClient.callApi(
-            '/api/enterprise/users/{userId}', 'GET',
-            pathParams, queryParams, headerParams, formParams, postBody,
-            contentTypes, accepts, UserRepresentation);
+        return this.get({
+            path: '/api/enterprise/users/{userId}',
+            pathParams,
+            returnType: UserRepresentation
+        });
     }
     /**
         * Query users
@@ -127,13 +101,8 @@ export class UsersApi extends BaseApi {
         */
     getUsers(opts?: any): Promise<ResultListDataRepresentationLightUserRepresentation> {
         opts = opts || {};
-        let postBody = null;
-
-        let pathParams = {
 
-        };
-
-        let queryParams = {
+        const queryParams = {
             'filter': opts['filter'],
             'email': opts['email'],
             'externalId': opts['externalId'],
@@ -144,19 +113,11 @@ export class UsersApi extends BaseApi {
             'tenantId': opts['tenantId']
         };
 
-        let headerParams = {
-
-        };
-        let formParams = {
-        };
-
-        let contentTypes = ['application/json'];
-        let accepts = ['application/json'];
-
-        return this.apiClient.callApi(
-            '/api/enterprise/users', 'GET',
-            pathParams, queryParams, headerParams, formParams, postBody,
-            contentTypes, accepts, ResultListDataRepresentationLightUserRepresentation);
+        return this.get({
+            path: '/api/enterprise/users',
+            queryParams,
+            returnType: ResultListDataRepresentationLightUserRepresentation
+        });
     }
     /**
         * Request a password reset
@@ -169,28 +130,10 @@ export class UsersApi extends BaseApi {
     requestPasswordReset(resetPassword: ResetPasswordRepresentation): Promise<any> {
         throwIfNotDefined(resetPassword, 'resetPassword');
 
-        let postBody = resetPassword;
-
-        let pathParams = {
-
-        };
-
-        let queryParams = {
-        };
-
-        let headerParams = {
-
-        };
-        let formParams = {
-        };
-
-        let contentTypes = ['application/json'];
-        let accepts = ['application/json'];
-
-        return this.apiClient.callApi(
-            '/api/enterprise/idm/passwords', 'POST',
-            pathParams, queryParams, headerParams, formParams, postBody,
-            contentTypes, accepts);
+        return this.post({
+            path: '/api/enterprise/idm/passwords',
+            bodyParam: resetPassword
+        });
     }
     /**
         * Update a user
@@ -205,28 +148,15 @@ export class UsersApi extends BaseApi {
         throwIfNotDefined(userId, 'userId');
         throwIfNotDefined(userRequest, 'userRequest');
 
-        let postBody = userRequest;
-
-        let pathParams = {
-            'userId': userId
+        const pathParams = {
+            userId
         };
 
-        let queryParams = {
-        };
-
-        let headerParams = {
-
-        };
-        let formParams = {
-        };
-
-        let contentTypes = ['application/json'];
-        let accepts = ['application/json'];
-
-        return this.apiClient.callApi(
-            '/api/enterprise/users/{userId}', 'PUT',
-            pathParams, queryParams, headerParams, formParams, postBody,
-            contentTypes, accepts, UserRepresentation);
+        return this.put({
+            path: '/api/enterprise/users/{userId}',
+            pathParams,
+            bodyParam: userRequest,
+            returnType: UserRepresentation
+        });
     }
-
 }
diff --git a/src/api/activiti-rest-api/model/taskRepresentation.ts b/src/api/activiti-rest-api/model/taskRepresentation.ts
@@ -85,8 +85,8 @@ export class TaskRepresentation {
         let fullName: string = '';
 
         if (this.assignee) {
-            let firstName: string = this.assignee.firstName ? this.assignee.firstName : '';
-            let lastName: string = this.assignee.lastName ? this.assignee.lastName : '';
+            const firstName: string = this.assignee.firstName ? this.assignee.firstName : '';
+            const lastName: string = this.assignee.lastName ? this.assignee.lastName : '';
             fullName = `${firstName} ${lastName}`;
         }