Merge pull request #7437 from PhakornKiong/docs/plugin-msgraph

Add documentation to msgraph plugin

plugins/catalog-backend-module-msgraph/api-report.md

@@ -61,12 +61,9 @@ export const MICROSOFT_GRAPH_TENANT_ID_ANNOTATION =
 // @public
 export const MICROSOFT_GRAPH_USER_ID_ANNOTATION = 'graph.microsoft.com/user-id';
 
-// Warning: (ae-missing-release-tag) "MicrosoftGraphClient" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal)
-//
-// @public (undocumented)
+// @public
 export class MicrosoftGraphClient {
   constructor(baseUrl: string, pca: msal.ConfidentialClientApplication);
-  // (undocumented)
   static create(config: MicrosoftGraphProviderConfig): MicrosoftGraphClient;
   // Warning: (ae-forgotten-export) The symbol "GroupMember" needs to be exported by the entry point index.d.ts
   //
@@ -94,13 +91,12 @@ export class MicrosoftGraphClient {
   getUserProfile(userId: string): Promise<MicrosoftGraph.User>;
   // (undocumented)
   getUsers(query?: ODataQuery): AsyncIterable<MicrosoftGraph.User>;
-  // (undocumented)
+  // Warning: (ae-unresolved-link) The @link reference could not be resolved: The package "@backstage/plugin-catalog-backend-module-msgraph" does not have an export "ODataQuery"
   requestApi(path: string, query?: ODataQuery): Promise<Response>;
   // Warning: (ae-forgotten-export) The symbol "ODataQuery" needs to be exported by the entry point index.d.ts
   //
   // (undocumented)
   requestCollection<T>(path: string, query?: ODataQuery): AsyncIterable<T>;
-  // (undocumented)
   requestRaw(url: string): Promise<Response>;
 }
 

plugins/catalog-backend-module-msgraph/src/microsoftGraph/client.ts

@@ -20,9 +20,24 @@ import fetch from 'cross-fetch';
 import qs from 'qs';
 import { MicrosoftGraphProviderConfig } from './config';
 
+/**
+ * OData (Open Data Protocol) Query
+ *
+ * {@link https://docs.microsoft.com/en-us/odata/concepts/queryoptions-overview}
+ * @public
+ */
 export type ODataQuery = {
+  /**
+   * filter a collection of resources
+   */
   filter?: string;
+  /**
+   * specifies the related resources or media streams to be included in line with retrieved resources
+   */
   expand?: string[];
+  /**
+   * request a specific set of properties for each entity or complex type
+   */
   select?: string[];
 };
 
@@ -30,7 +45,23 @@ export type GroupMember =
   | (MicrosoftGraph.Group & { '@odata.type': '#microsoft.graph.user' })
   | (MicrosoftGraph.User & { '@odata.type': '#microsoft.graph.group' });
 
+/**
+ * A HTTP Client that communicates with Microsoft Graph API.
+ * Simplify Authentication and API calls to get `User` and `Group` from Azure Active Directory
+ *
+ * Uses `msal-node` for authentication
+ *
+ * @public
+ */
 export class MicrosoftGraphClient {
+  /**
+   * Factory method that instantiate `msal` client and return
+   * an instance of `MicrosoftGraphClient`
+   *
+   * @public
+   *
+   * @param config - Configuration for Interacting with Graph API
+   */
   static create(config: MicrosoftGraphProviderConfig): MicrosoftGraphClient {
     const clientConfig: msal.Configuration = {
       auth: {
@@ -43,6 +74,11 @@ export class MicrosoftGraphClient {
     return new MicrosoftGraphClient(config.target, pca);
   }
 
+  /**
+   * @param baseUrl - baseUrl of Graph API {@link MicrosoftGraphProviderConfig.target}
+   * @param pca - instance of `msal.ConfidentialClientApplication` that is used to acquire token for Graph API calls
+   *
+   */
   constructor(
     private readonly baseUrl: string,
     private readonly pca: msal.ConfidentialClientApplication,
@@ -73,6 +109,13 @@ export class MicrosoftGraphClient {
     }
   }
 
+  /**
+   * Abstract on top of {@link MicrosoftGraphClient.requestRaw}
+   *
+   * @public
+   * @param path - Resource in Microsoft Graph
+   * @param query - OData Query {@link ODataQuery}
+   */
   async requestApi(path: string, query?: ODataQuery): Promise<Response> {
     const queryString = qs.stringify(
       {
@@ -90,6 +133,11 @@ export class MicrosoftGraphClient {
     return await this.requestRaw(`${this.baseUrl}/${path}${queryString}`);
   }
 
+  /**
+   * Makes a HTTP call to Graph API with token
+   *
+   * @param url - HTTP Endpoint of Graph API
+   */
   async requestRaw(url: string): Promise<Response> {
     // Make sure that we always have a valid access token (might be cached)
     const token = await this.pca.acquireTokenByClientCredential({