@c8y/api-doc 1023.48.0

package/src/app/api-doc-app.model.ts

@@ -0,0 +1,10 @@
+import { IApplication } from '@c8y/client';
+
+export interface ApiDocApp extends IApplication {
+  appLabel: string;
+  downloadPath: string;
+  manifest: {
+    openApiSpec?: string;
+    [key: string]: any;
+  };
+}

package/src/app/api-doc-home/api-doc-home.component.html

@@ -0,0 +1,108 @@
+<c8y-title>API Documentation</c8y-title>
+
+<div class="card">
+  <div class="card-block p-32">
+    <h1 translate>Welcome to Cumulocity API Documentation</h1>
+    <p
+      class="m-b-16 text-muted"
+      translate
+    >
+      Your comprehensive, version-aligned API reference for the Cumulocity IoT Platform
+    </p>
+    <hr class="m-b-16" />
+    <p
+      class="m-b-24"
+      translate
+    >
+      This application provides complete API documentation extracted directly from your installed
+      Cumulocity core and microservices. Every endpoint, parameter, and response is automatically
+      synchronized with your current platform version, ensuring accuracy and reliability.
+    </p>
+  </div>
+</div>
+
+<div
+  class="card-group"
+  aria-label="API documentation features"
+  role="list"
+>
+  <!-- Card 1: How to Use -->
+  <div
+    class="col-lg-6"
+    role="listitem"
+  >
+    <div class="card">
+      <div class="card-header separator">
+        <p
+          class="card-title"
+          translate
+        >
+          How to use this app
+        </p>
+      </div>
+      <div class="card-block">
+        <p translate>
+          This application provides comprehensive API documentation using the industry-standard
+          Swagger/OpenAPI format. Each API endpoint is fully documented with:
+        </p>
+        <ul class="m-t-16 m-b-16">
+          <li>
+            <strong translate>Complete specifications:</strong>
+            <p translate>Parameters, request/response schemas, and examples</p>
+          </li>
+          <li>
+            <strong translate>Try it out:</strong>
+            <p translate>Execute API calls directly from your browser using your current session</p>
+          </li>
+          <li>
+            <strong translate>Code samples:</strong>
+            <p translate>See real request and response examples for each endpoint</p>
+          </li>
+        </ul>
+      </div>
+    </div>
+  </div>
+
+  <!-- Card 2: API List -->
+  <div
+    class="col-lg-6"
+    role="listitem"
+  >
+    <div class="card">
+      <div class="card-header separator">
+        <p
+          class="card-title"
+          translate
+        >
+          Available APIs
+        </p>
+      </div>
+      <c8y-list-group
+        class="c8y-nav-stacked"
+        role="list"
+      >
+        @for (app of documentedApps$ | async; track app.id) {
+          <c8y-li
+            class="c8y-stacked-item"
+            role="listitem"
+            [selectable]="false"
+            [routerLink]="`/api-docs/${app.id}`"
+          >
+            <c8y-li-icon>
+              <c8y-app-icon
+                class="icon-40"
+                [app]="app"
+              ></c8y-app-icon>
+            </c8y-li-icon>
+            <c8y-li-body class="icon-flex">
+              <strong>{{ app.appLabel }}</strong>
+            </c8y-li-body>
+            <c8y-li-footer translate>
+              {{ app.description || 'No description provided' }}
+            </c8y-li-footer>
+          </c8y-li>
+        }
+      </c8y-list-group>
+    </div>
+  </div>
+</div>

package/src/app/api-doc-home/api-doc-home.component.ts

@@ -0,0 +1,36 @@
+import { AsyncPipe } from '@angular/common';
+import { Component, inject } from '@angular/core';
+import { RouterLink } from '@angular/router';
+import {
+  AppIconComponent,
+  C8yTranslateDirective,
+  ListGroupComponent,
+  ListItemBodyComponent,
+  ListItemComponent,
+  ListItemFooterComponent,
+  ListItemIconComponent,
+  TitleComponent
+} from '@c8y/ngx-components';
+import { ApiDocService } from '../api-doc.service';
+
+@Component({
+  selector: 'api-doc-home',
+  templateUrl: './api-doc-home.component.html',
+  standalone: true,
+  imports: [
+    TitleComponent,
+    ListGroupComponent,
+    ListItemComponent,
+    ListItemIconComponent,
+    ListItemBodyComponent,
+    ListItemFooterComponent,
+    AsyncPipe,
+    RouterLink,
+    C8yTranslateDirective,
+    AppIconComponent
+  ]
+})
+export class ApiDocHomeComponent {
+  private apiDocService = inject(ApiDocService);
+  documentedApps$ = this.apiDocService.getApiDocApps();
+}

package/src/app/api-doc-navigator.factory.ts

@@ -0,0 +1,36 @@
+import { inject, Injectable } from '@angular/core';
+import { ExtensionFactory, NavigatorNode } from '@c8y/ngx-components';
+import { map, Observable } from 'rxjs';
+import { ApiDocApp } from './api-doc-app.model';
+import { ApiDocService } from './api-doc.service';
+import { gettext } from '@c8y/ngx-components/gettext';
+import { createAppIconComponent } from './app-icon/app-icon-navigator.component';
+
+@Injectable({
+  providedIn: 'root'
+})
+export class ApiDocNavigatorFactory implements ExtensionFactory<NavigatorNode> {
+  private apiDocService = inject(ApiDocService);
+
+  get(): Observable<NavigatorNode> {
+    return this.apiDocService.getApiDocApps().pipe(
+      map(apps => {
+        return new NavigatorNode({
+          path: 'api-docs',
+          icon: 'api',
+          label: gettext('API Documentation'),
+          priority: 1000,
+          children: apps.map(
+            (app: ApiDocApp, index: number) =>
+              new NavigatorNode({
+                label: app.appLabel,
+                iconComponent: createAppIconComponent(app),
+                path: `/api-docs/${app.id}`,
+                priority: index * -1
+              })
+          )
+        });
+      })
+    );
+  }
+}

package/src/app/api-doc.providers.ts

@@ -0,0 +1,18 @@
+import { hookNavigator, hookRoute } from '@c8y/ngx-components';
+import { ApiDocNavigatorFactory } from './api-doc-navigator.factory';
+
+export const apiDocProviders = [
+  hookRoute([
+    {
+      path: 'api-docs',
+      loadComponent: () =>
+        import('./api-doc-home/api-doc-home.component').then(m => m.ApiDocHomeComponent)
+    },
+    {
+      path: 'api-docs/:id',
+
+      loadComponent: () => import('./swagger/swagger.component').then(m => m.SwaggerComponent)
+    }
+  ]),
+  hookNavigator(ApiDocNavigatorFactory)
+];

package/src/app/api-doc.service.ts

@@ -0,0 +1,100 @@
+import { inject, Injectable } from '@angular/core';
+import { ApplicationService } from '@c8y/client';
+import { AppStateService, HumanizeAppNamePipe } from '@c8y/ngx-components';
+import { combineLatest, from, map, Observable, of, shareReplay, switchMap, take } from 'rxjs';
+import { ApiDocApp } from './api-doc-app.model';
+import { sortBy } from 'lodash';
+import { gettext } from '@c8y/ngx-components/gettext';
+
+@Injectable({
+  providedIn: 'root'
+})
+export class ApiDocService {
+  private appService = inject(ApplicationService);
+  private appStateService = inject(AppStateService);
+  private humanize = inject(HumanizeAppNamePipe);
+  private cache$: Observable<ApiDocApp[]> | null = null;
+
+  private readonly CORE_API_DOCS_APP: ApiDocApp = {
+    id: 'core-api',
+    name: gettext('Core API'),
+    description: gettext('Cumulocity IoT Core API Documentation'),
+    contextPath: 'api-doc',
+    downloadPath: './c8y-oas.yml',
+    icon: {
+      class: 'c8y-icon-cumulocity-iot'
+    },
+    manifest: {
+      openApiSpec: 'c8y-oas.yml'
+    },
+    appLabel: gettext('Core API')
+  };
+
+  /**
+   * Get all applications that have API documentation.
+   * Results are cached and shared across subscribers.
+   */
+  getApiDocApps(): Observable<ApiDocApp[]> {
+    if (!this.cache$) {
+      this.cache$ = combineLatest([
+        from(this.appService.list({ pageSize: 2000 })),
+        this.appStateService.currentApplication
+      ]).pipe(
+        map(([apps, currentApp]) => {
+          // Update coreApiDocApps with current app's contextPath
+          const coreApiDoc: ApiDocApp = {
+            ...this.CORE_API_DOCS_APP,
+            contextPath: currentApp?.contextPath || 'api-doc'
+          };
+
+          // Filter apps with openApiSpec
+          const appsWithOpenApiSpec = apps.data.filter(
+            app => !!(app.manifest && app.manifest['openApiSpec'])
+          );
+          return {
+            appsWithOpenApiSpec: sortBy(appsWithOpenApiSpec, app => app.name?.toLowerCase() || ''),
+            coreApiDoc
+          };
+        }),
+        switchMap(({ appsWithOpenApiSpec, coreApiDoc }) => {
+          if (appsWithOpenApiSpec.length === 0) {
+            return of([coreApiDoc] as ApiDocApp[]);
+          }
+          const appObservables = appsWithOpenApiSpec.map(app =>
+            this.humanize.transform(app.name).pipe(
+              map(
+                humanizedName =>
+                  ({
+                    ...app,
+                    appLabel: humanizedName,
+                    downloadPath: `/service/${app.contextPath}/${app.manifest['openApiSpec']}`
+                  }) as ApiDocApp
+              )
+            )
+          );
+          return combineLatest(appObservables).pipe(map(apiDocApps => [coreApiDoc, ...apiDocApps]));
+        }),
+        shareReplay(1)
+      );
+    }
+    return this.cache$;
+  }
+
+  /**
+   * Get a specific API doc app by ID.
+   * Uses cached data if available, otherwise fetches all apps.
+   */
+  getApiDocById(id: string | number): Observable<ApiDocApp | undefined> {
+    return this.getApiDocApps().pipe(
+      take(1),
+      map(apps => apps.find(app => app.id === id?.toString()))
+    );
+  }
+
+  /**
+   * Clear the cache and force a refresh on next call
+   */
+  clearCache(): void {
+    this.cache$ = null;
+  }
+}

package/src/app/app-icon/app-icon-navigator.component.html

@@ -0,0 +1,4 @@
+<c8y-app-icon
+  class="icon-16 api-app-navigator-icon"
+  [app]="app"
+></c8y-app-icon>

package/src/app/app-icon/app-icon-navigator.component.less

@@ -0,0 +1,13 @@
+.api-app-navigator-icon {
+  width: 24px;
+  margin-left: 16px;
+  display: flex;
+  justify-content: center;
+
+  ::ng-deep .app-noicon {
+    width: 22px;
+    height: 22px;
+    font-size: 14px;
+    line-height: 22px;
+  }
+}

package/src/app/app-icon/app-icon-navigator.component.ts

@@ -0,0 +1,17 @@
+import { Component } from '@angular/core';
+import { AppIconComponent } from '@c8y/ngx-components';
+
+export function createAppIconComponent(app: any) {
+  @Component({
+    selector: 'api-app-icon-navigator',
+    templateUrl: './app-icon-navigator.component.html',
+    styleUrls: ['./app-icon-navigator.component.less'],
+    standalone: true,
+    imports: [AppIconComponent]
+  })
+  class AppIconNavigatorComponent {
+    app = app;
+  }
+
+  return AppIconNavigatorComponent;
+}

package/src/app/app.config.ts

@@ -0,0 +1,18 @@
+import { ApplicationConfig, importProvidersFrom } from '@angular/core';
+import { provideAnimations } from '@angular/platform-browser/animations';
+import { CoreModule, hookRoute, RouterModule } from '@c8y/ngx-components';
+
+export const appConfig: ApplicationConfig = {
+  providers: [
+    provideAnimations(),
+    importProvidersFrom(RouterModule.forRoot()),
+    importProvidersFrom(CoreModule.forRoot()),
+    hookRoute([
+      {
+        path: '',
+        redirectTo: 'api-docs',
+        pathMatch: 'full'
+      }
+    ])
+  ]
+};

package/src/app/swagger/swagger.component.html

@@ -0,0 +1,54 @@
+<c8y-title>
+  {{ (spec$ | async)?.app.appLabel | translate }}
+</c8y-title>
+
+<c8y-action-bar-item [placement]="'right'">
+  <button
+    class="btn btn-link"
+    title="{{ 'Download' | translate }}"
+    type="button"
+    (click)="downloadSpecFile()"
+  >
+    <i
+      class="m-r-4"
+      [c8yIcon]="'download'"
+    ></i>
+    <span translate>Download</span>
+  </button>
+</c8y-action-bar-item>
+@if (!(shouldHideAlert$ | async)) {
+  <div class="d-flex j-c-center m-t-16 m-b-16">
+    <div
+      class="alert alert-warning"
+      role="alert"
+    >
+      <button
+        class="close"
+        aria-label="Close alert"
+        type="button"
+        (click)="hideAlert()"
+      >
+        <span aria-hidden="true">
+          <i [c8yIcon]="'times'"></i>
+        </span>
+        <span class="sr-only">Close</span>
+      </button>
+      <strong translate>Authenticated requests (use with caution):</strong>
+      <p translate>
+        Authentication is provided via the current application session (cookie based). When you copy
+        cURL snippets, ensure you include the session cookie or any other authentication method, to
+        authenticate your requests.
+      </p>
+      <p translate>
+        The "Try it out" feature executes real API calls against your live system. DELETE, PUT, and
+        POST operations will modify or remove data permanently. Always verify your inputs before
+        executing destructive operations.
+      </p>
+    </div>
+  </div>
+}
+
+<div
+  id="api-documentation"
+  #apiDocElement
+></div>

package/src/app/swagger/swagger.component.less

@@ -0,0 +1,274 @@
+@import '~swagger-ui-dist/swagger-ui.css';
+
+.swagger-ui .info .title small pre {
+  background: transparent !important;
+  border: 0;
+}
+
+.swagger-ui .opblock-body pre.microlight {
+  background-color: var(--c8y-palette-gray-10) !important;
+}
+
+body .swagger-ui .info {
+  h1,
+  h2,
+  h3,
+  h4,
+  h5,
+  li,
+  p,
+  table {
+    color: var(--text-color, var(--c8y-text-color));
+  }
+}
+
+body .swagger-ui {
+  font-family: var(--c8y-font-family-base) !important;
+
+  *:not(pre):not(code):not(.model):not(pre code span):not(.body-param__text):not(.property-row):not(
+      .property-row td
+    ):not(.model-title__text):not(.headerline) {
+    font-family: var(--c8y-font-family-base) !important;
+  }
+
+  .wrapper {
+    padding: 0;
+    margin: 0;
+  }
+
+  .info {
+    margin: 0;
+
+    .title {
+      display: flex;
+      align-items: center;
+
+      small {
+        top: 0;
+        vertical-align: unset;
+
+        pre {
+          font-family: var(--c8y-font-family-base) !important;
+          padding: 0 4px;
+        }
+      }
+    }
+  }
+
+  .servers > label {
+    margin-top: 0;
+  }
+
+  .scheme-container {
+    padding-top: 0;
+    box-shadow: var(--c8y-elevation-sm);
+    background: var(--c8y-level-1);
+    padding: 16px 16px;
+    border: 1px solid var(--c8y-root-component-border-color);
+    max-width: 1460px;
+  }
+
+  .opblock-tag-section {
+    box-shadow: var(--c8y-elevation-sm);
+    margin-bottom: 24px;
+  }
+
+  .operation-tag-content {
+    padding: 16px;
+  }
+
+  .opblock-tag {
+    margin: 0;
+    padding: 16px;
+    border: 0;
+    box-shadow: inset 0 -1px 0
+      var(--c8y-component-border-color, var(--c8y-root-component-border-color));
+    display: flex;
+    flex-wrap: wrap;
+    align-items: flex-start;
+
+    &:hover {
+      color: var(--c8y-brand-primary);
+      background-color: transparent;
+    }
+
+    > a {
+      flex: 0 0 auto;
+    }
+
+    > small {
+      order: 3;
+      flex: 1 1 100%;
+      font-size: 14px;
+      line-height: 1.5;
+      margin-top: 12px;
+      display: block;
+    }
+
+    > .expand-operation {
+      margin-left: auto;
+    }
+  }
+
+  .scheme-container .schemes .auth-wrapper .authorize {
+    align-items: center;
+    color: var(--c8y-btn-default-color-default);
+    background-color: var(--c8y-btn-default-background-default);
+    border-color: var(--c8y-btn-default-border-color-default);
+
+    &:hover,
+    &:focus {
+      color: var(--c8y-btn-default-color-hover);
+      background-color: var(--c8y-btn-default-background-hover);
+      border-color: var(--c8y-btn-default-border-color-hover);
+      box-shadow: inset 0 0 0 1px var(--c8y-btn-default-border-color-hover);
+    }
+
+    svg {
+      fill: var(--c8y-btn-default-color-default);
+    }
+
+    span {
+      padding: 0;
+    }
+  }
+
+  .opblock .opblock-summary-operation-id,
+  .opblock .opblock-summary-path,
+  .opblock .opblock-summary-path__deprecated,
+  .model,
+  code,
+  .models .model-box {
+    &,
+    * {
+      font-family: monospace !important;
+    }
+  }
+
+  .opblock-body pre.microlight {
+    font-family: monospace !important;
+    font-weight: 400;
+
+    pre code *,
+    pre code span {
+      font-family: monospace !important;
+    }
+  }
+
+  table {
+    background-color: transparent;
+  }
+
+  svg {
+    width: unset;
+    height: unset;
+  }
+
+  select {
+    font-weight: 400;
+    border: 1px solid var(--c8y-form-control-border-color-default);
+    background-color: var(--c8y-form-control-background-default);
+    box-shadow: none;
+    border-radius: 0;
+
+    &:focus {
+      border-color: var(--c8y-form-control-border-color-focus);
+      box-shadow: inset 0 0 0 2px var(--c8y-form-control-border-color-focus);
+      border-radius: 2px;
+    }
+  }
+
+  .btn {
+    box-shadow: none;
+    padding: 5px 16px;
+    font-weight: 400;
+    border: 1px solid var(--c8y-btn-default-border-color-default);
+    background-color: var(--c8y-btn-default-background-default);
+    color: var(--c8y-btn-default-color-default);
+    border-radius: calc(var(--btn-border-radius-base, var(--c8y-btn-border-radius-base)) * 1px);
+
+    &:hover,
+    &:focus {
+      box-shadow: inset 0 0 0 1px var(--c8y-btn-default-border-color-hover);
+    }
+  }
+
+  .model-box-control:focus,
+  .models-control:focus,
+  .opblock-summary-control:focus {
+    outline-color: var(--c8y-brand-primary);
+  }
+
+  .markdown code,
+  .renderedMarkdown code {
+    color: var(--c8y-code-color);
+    background: var(--c8y-code-background);
+  }
+
+  .opblock.opblock-get {
+    border-color: var(--c8y-palette-status-info-light);
+
+    .opblock-summary {
+      border-color: var(--c8y-palette-status-info-light);
+    }
+
+    .opblock-summary-method {
+      background: var(--c8y-palette-status-info);
+    }
+  }
+
+  .opblock.opblock-put {
+    border-color: var(--c8y-palette-status-warning-light);
+
+    .opblock-summary {
+      border-color: var(--c8y-palette-status-warning-light);
+    }
+
+    .opblock-summary-method {
+      background: var(--c8y-palette-status-warning);
+    }
+  }
+
+  .opblock.opblock-post {
+    border-color: var(--c8y-palette-status-success-light);
+
+    .opblock-summary {
+      border-color: var(--c8y-palette-status-success-light);
+    }
+
+    .opblock-summary-method {
+      background: var(--c8y-palette-status-success);
+    }
+  }
+
+  .opblock.opblock-delete {
+    border-color: var(--c8y-palette-status-danger-light);
+
+    .opblock-summary {
+      border-color: var(--c8y-palette-status-danger-light);
+    }
+
+    .opblock-summary-method {
+      background: var(--c8y-palette-status-danger);
+    }
+  }
+
+  section.models {
+    border-radius: 0;
+    border: 0;
+    box-shadow: var(--c8y-elevation-sm);
+
+    > h4 {
+      padding: 0;
+      font-size: 24px;
+      border: 0 !important;
+      margin: 0 !important;
+      box-shadow: inset 0 -1px 0
+        var(--c8y-component-border-color, var(--c8y-root-component-border-color));
+
+      .models-control {
+        padding: 16px;
+      }
+    }
+  }
+}