src/api-viewer/APIViewer.js

   1 /*global apiSchema*/
   2
   3 Ext.onReady(function() {
   4     Ext.define('pmx-param-schema', {
   5         extend: 'Ext.data.Model',
   6         fields: [
   7             'name', 'type', 'typetext', 'description', 'verbose_description',
   8             'enum', 'minimum', 'maximum', 'minLength', 'maxLength',
   9             'pattern', 'title', 'requires', 'format', 'default',
  10             'disallow', 'extends', 'links',
  11             {
  12                 name: 'optional',
  13                 type: 'boolean',
  14             },
  15         ],
  16     });
  17
  18     let store = Ext.define('pmx-updated-treestore', {
  19         extend: 'Ext.data.TreeStore',
  20         model: Ext.define('pmx-api-doc', {
  21             extend: 'Ext.data.Model',
  22             fields: [
  23                 'path', 'info', 'text',
  24             ],
  25         }),
  26         proxy: {
  27             type: 'memory',
  28             data: apiSchema,
  29         },
  30         sorters: [{
  31             property: 'leaf',
  32             direction: 'ASC',
  33         }, {
  34             property: 'text',
  35             direction: 'ASC',
  36         }],
  37         filterer: 'bottomup',
  38         doFilter: function(node) {
  39             this.filterNodes(node, this.getFilters().getFilterFn(), true);
  40         },
  41
  42         filterNodes: function(node, filterFn, parentVisible) {
  43             let me = this,
  44                 bottomUpFiltering = me.filterer === 'bottomup',
  45                 match = filterFn(node) && parentVisible || (node.isRoot() && !me.getRootVisible()),
  46                 childNodes = node.childNodes,
  47                 len = childNodes && childNodes.length, i, matchingChildren;
  48
  49             if (len) {
  50                 for (i = 0; i < len; ++i) {
  51                     matchingChildren = me.filterNodes(childNodes[i], filterFn, match || bottomUpFiltering) || matchingChildren;
  52                 }
  53                 if (bottomUpFiltering) {
  54                     match = matchingChildren || match;
  55                 }
  56             }
  57
  58             node.set("visible", match, me._silentOptions);
  59             return match;
  60         },
  61
  62     }).create();
  63
  64     let render_description = function(value, metaData, record) {
  65         let pdef = record.data;
  66
  67         value = pdef.verbose_description || value;
  68
  69         // TODO: try to render asciidoc correctly
  70
  71         metaData.style = 'white-space:pre-wrap;';
  72
  73         return Ext.htmlEncode(value);
  74     };
  75
  76     let render_type = function(value, metaData, record) {
  77         let pdef = record.data;
  78
  79         return pdef.enum ? 'enum' : pdef.type || 'string';
  80     };
  81
  82     let render_simple_format = function(pdef, type_fallback) {
  83         if (pdef.typetext) {return pdef.typetext;}
  84
  85         if (pdef.enum) {return pdef.enum.join(' | ');}
  86
  87         if (pdef.format) {return pdef.format;}
  88
  89         if (pdef.pattern) {return pdef.pattern;}
  90
  91         if (pdef.type === 'boolean') {return `<true|false>`;}
  92
  93         if (type_fallback && pdef.type) {return `<${pdef.type}>`;}
  94     };
  95
  96     let render_format = function(value, metaData, record) {
  97         let pdef = record.data;
  98
  99         metaData.style = 'white-space:normal;';
 100
 101         if (pdef.type === 'array' && pdef.items) {
 102             let format = render_simple_format(pdef.items, true);
 103             return `[${Ext.htmlEncode(format)}, ...]`;
 104         }
 105
 106         return Ext.htmlEncode(render_simple_format(pdef) || '');
 107     };
 108
 109     let real_path = function(path) {
 110         return path.replace(/^.*\/_upgrade_(\/)?/, "/");
 111     };
 112
 113     let permission_text = function(permission) {
 114         let permhtml = "";
 115
 116         if (permission.user) {
 117             if (!permission.description) {
 118                 if (permission.user === 'world') {
 119                     permhtml += "Accessible without any authentication.";
 120                 } else if (permission.user === 'all') {
 121                     permhtml += "Accessible by all authenticated users.";
 122                 } else {
 123                     permhtml += 'Onyl accessible by user "' +
 124                         permission.user + '"';
 125                 }
 126             }
 127         } else if (permission.check) {
 128             permhtml += "<pre>Check: " +
 129                 Ext.htmlEncode(Ext.JSON.encode(permission.check)) + "</pre>";
 130         } else if (permission.userParam) {
 131             permhtml += `<div>Check if user matches parameter '${permission.userParam}'`;
 132         } else if (permission.or) {
 133             permhtml += "<div>Or<div style='padding-left: 10px;'>";
 134             Ext.Array.each(permission.or, function(sub_permission) {
 135                 permhtml += permission_text(sub_permission);
 136             });
 137             permhtml += "</div></div>";
 138         } else if (permission.and) {
 139             permhtml += "<div>And<div style='padding-left: 10px;'>";
 140             Ext.Array.each(permission.and, function(sub_permission) {
 141                 permhtml += permission_text(sub_permission);
 142             });
 143             permhtml += "</div></div>";
 144         } else {
 145             //console.log(permission);
 146             permhtml += "Unknown syntax!";
 147         }
 148
 149         return permhtml;
 150     };
 151
 152     let render_docu = function(data) {
 153         let md = data.info;
 154
 155         let items = [];
 156
 157         Ext.Array.each(['GET', 'POST', 'PUT', 'DELETE'], function(method) {
 158             let info = md[method];
 159             if (info) {
 160                 let usage = "";
 161
 162                 usage += "<table><tr><td>HTTP:&nbsp;&nbsp;&nbsp;</td><td>"
 163                     + method + " " + real_path("/api2/json" + data.path) + "</td></tr>";
 164
 165                 if (typeof cliusage === 'function') {
 166                     usage += cliusage(method, real_path(data.path));
 167                 }
 168
 169                 let sections = [
 170                     {
 171                         title: 'Description',
 172                         html: Ext.htmlEncode(info.description),
 173                         bodyPadding: 10,
 174                     },
 175                     {
 176                         title: 'Usage',
 177                         html: usage,
 178                         bodyPadding: 10,
 179                     },
 180                 ];
 181
 182                 if (info.parameters && info.parameters.properties) {
 183                     let pstore = Ext.create('Ext.data.Store', {
 184                         model: 'pmx-param-schema',
 185                         proxy: {
 186                             type: 'memory',
 187                         },
 188                         groupField: 'optional',
 189                         sorters: [
 190                             {
 191                                 property: 'name',
 192                                 direction: 'ASC',
 193                             },
 194                         ],
 195                     });
 196
 197                     Ext.Object.each(info.parameters.properties, function(name, pdef) {
 198                         pdef.name = name;
 199                         pstore.add(pdef);
 200                     });
 201
 202                     pstore.sort();
 203
 204                     let groupingFeature = Ext.create('Ext.grid.feature.Grouping', {
 205                         enableGroupingMenu: false,
 206                         groupHeaderTpl: '<tpl if="groupValue">Optional</tpl><tpl if="!groupValue">Required</tpl>',
 207                     });
 208
 209                     sections.push({
 210                         xtype: 'gridpanel',
 211                         title: 'Parameters',
 212                         features: [groupingFeature],
 213                         store: pstore,
 214                         viewConfig: {
 215                             trackOver: false,
 216                             stripeRows: true,
 217                         },
 218                         columns: [
 219                             {
 220                                 header: 'Name',
 221                                 dataIndex: 'name',
 222                                 flex: 1,
 223                             },
 224                             {
 225                                 header: 'Type',
 226                                 dataIndex: 'type',
 227                                 renderer: render_type,
 228                                 flex: 1,
 229                             },
 230                             {
 231                                 header: 'Default',
 232                                 dataIndex: 'default',
 233                                 flex: 1,
 234                             },
 235                             {
 236                                 header: 'Format',
 237                                 dataIndex: 'type',
 238                                 renderer: render_format,
 239                                 flex: 2,
 240                             },
 241                             {
 242                                 header: 'Description',
 243                                 dataIndex: 'description',
 244                                 renderer: render_description,
 245                                 flex: 6,
 246                             },
 247                         ],
 248                     });
 249                 }
 250
 251                 if (info.returns) {
 252                     let retinf = info.returns;
 253                     let rtype = retinf.type;
 254                     if (!rtype && retinf.items) {rtype = 'array';}
 255                     if (!rtype) {rtype = 'object';}
 256
 257                     let rpstore = Ext.create('Ext.data.Store', {
 258                         model: 'pmx-param-schema',
 259                         proxy: {
 260                             type: 'memory',
 261                         },
 262                         groupField: 'optional',
 263                         sorters: [
 264                             {
 265                                 property: 'name',
 266                                 direction: 'ASC',
 267                            },
 268                         ],
 269                     });
 270
 271                     let properties;
 272                     if (rtype === 'array' && retinf.items.properties) {
 273                         properties = retinf.items.properties;
 274                     }
 275
 276                     if (rtype === 'object' && retinf.properties) {
 277                         properties = retinf.properties;
 278                     }
 279
 280                     Ext.Object.each(properties, function(name, pdef) {
 281                         pdef.name = name;
 282                         rpstore.add(pdef);
 283                     });
 284
 285                     rpstore.sort();
 286
 287                     let groupingFeature = Ext.create('Ext.grid.feature.Grouping', {
 288                         enableGroupingMenu: false,
 289                         groupHeaderTpl: '<tpl if="groupValue">Optional</tpl><tpl if="!groupValue">Obligatory</tpl>',
 290                     });
 291                     let returnhtml;
 292                     if (retinf.items) {
 293                         returnhtml = '<pre>items: ' + Ext.htmlEncode(JSON.stringify(retinf.items, null, 4)) + '</pre>';
 294                     }
 295
 296                     if (retinf.properties) {
 297                         returnhtml = returnhtml || '';
 298                         returnhtml += '<pre>properties:' + Ext.htmlEncode(JSON.stringify(retinf.properties, null, 4)) + '</pre>';
 299                     }
 300
 301                     let rawSection = Ext.create('Ext.panel.Panel', {
 302                         bodyPadding: '0px 10px 10px 10px',
 303                         html: returnhtml,
 304                         hidden: true,
 305                     });
 306
 307                     sections.push({
 308                         xtype: 'gridpanel',
 309                         title: 'Returns: ' + rtype,
 310                         features: [groupingFeature],
 311                         store: rpstore,
 312                         viewConfig: {
 313                             trackOver: false,
 314                             stripeRows: true,
 315                         },
 316                     columns: [
 317                         {
 318                             header: 'Name',
 319                             dataIndex: 'name',
 320                             flex: 1,
 321                         },
 322                         {
 323                             header: 'Type',
 324                             dataIndex: 'type',
 325                             renderer: render_type,
 326                             flex: 1,
 327                         },
 328                         {
 329                             header: 'Default',
 330                             dataIndex: 'default',
 331                             flex: 1,
 332                         },
 333                         {
 334                             header: 'Format',
 335                             dataIndex: 'type',
 336                             renderer: render_format,
 337                             flex: 2,
 338                         },
 339                         {
 340                             header: 'Description',
 341                             dataIndex: 'description',
 342                             renderer: render_description,
 343                             flex: 6,
 344                         },
 345                     ],
 346                     bbar: [
 347                         {
 348                             xtype: 'button',
 349                             text: 'Show RAW',
 350                             handler: function(btn) {
 351                                 rawSection.setVisible(!rawSection.isVisible());
 352                                 btn.setText(rawSection.isVisible() ? 'Hide RAW' : 'Show RAW');
 353                             },
 354 },
 355                     ],
 356                 });
 357
 358                 sections.push(rawSection);
 359                 }
 360
 361                 if (!data.path.match(/\/_upgrade_/)) {
 362                     let permhtml = '';
 363
 364                     if (!info.permissions) {
 365                         permhtml = "Root only.";
 366                     } else {
 367                         if (info.permissions.description) {
 368                             permhtml += "<div style='white-space:pre-wrap;padding-bottom:10px;'>" +
 369                                 Ext.htmlEncode(info.permissions.description) + "</div>";
 370                         }
 371                         permhtml += permission_text(info.permissions);
 372                     }
 373
 374                     if (info.allowtoken !== undefined && !info.allowtoken) {
 375                         permhtml += "<br />This API endpoint is not available for API tokens.";
 376                     }
 377
 378                     sections.push({
 379                         title: 'Required permissions',
 380                         bodyPadding: 10,
 381                         html: permhtml,
 382                     });
 383                 }
 384
 385                 items.push({
 386                     title: method,
 387                     autoScroll: true,
 388                     defaults: {
 389                         border: false,
 390                     },
 391                     items: sections,
 392                 });
 393             }
 394         });
 395
 396         let ct = Ext.getCmp('docview');
 397         ct.setTitle("Path: " + real_path(data.path));
 398         ct.removeAll(true);
 399         ct.add(items);
 400         ct.setActiveTab(0);
 401     };
 402
 403     Ext.define('Ext.form.SearchField', {
 404         extend: 'Ext.form.field.Text',
 405         alias: 'widget.searchfield',
 406
 407         emptyText: 'Search...',
 408
 409         flex: 1,
 410
 411         inputType: 'search',
 412         listeners: {
 413             'change': function() {
 414                 let value = this.getValue();
 415                 if (!Ext.isEmpty(value)) {
 416                     store.filter({
 417                         property: 'path',
 418                         value: value,
 419                         anyMatch: true,
 420                     });
 421                 } else {
 422                     store.clearFilter();
 423                 }
 424             },
 425         },
 426     });
 427
 428     let tree = Ext.create('Ext.tree.Panel', {
 429         title: 'Resource Tree',
 430         tbar: [
 431             {
 432                 xtype: 'searchfield',
 433             },
 434         ],
 435         tools: [
 436             {
 437                 type: 'expand',
 438                 tooltip: 'Expand all',
 439                 tooltipType: 'title',
 440                 callback: (tree) => tree.expandAll(),
 441             },
 442             {
 443                 type: 'collapse',
 444                 tooltip: 'Collapse all',
 445                 tooltipType: 'title',
 446                 callback: (tree) => tree.collapseAll(),
 447             },
 448         ],
 449         store: store,
 450         width: 200,
 451         region: 'west',
 452         split: true,
 453         margins: '5 0 5 5',
 454         rootVisible: false,
 455         listeners: {
 456             selectionchange: function(v, selections) {
 457                 if (!selections[0]) {return;}
 458                 let rec = selections[0];
 459                 render_docu(rec.data);
 460                 location.hash = '#' + rec.data.path;
 461             },
 462         },
 463     });
 464
 465     Ext.create('Ext.container.Viewport', {
 466         layout: 'border',
 467         renderTo: Ext.getBody(),
 468         items: [
 469             tree,
 470             {
 471                 xtype: 'tabpanel',
 472                 title: 'Documentation',
 473                 id: 'docview',
 474                 region: 'center',
 475                 margins: '5 5 5 0',
 476                 layout: 'fit',
 477                 items: [],
 478             },
 479         ],
 480     });
 481
 482     let deepLink = function() {
 483         let path = window.location.hash.substring(1).replace(/\/\s*$/, '');
 484         let endpoint = store.findNode('path', path);
 485
 486         if (endpoint) {
 487             tree.getSelectionModel().select(endpoint);
 488             tree.expandPath(endpoint.getPath());
 489             render_docu(endpoint.data);
 490         }
 491     };
 492     window.onhashchange = deepLink;
 493
 494     deepLink();
 495 });