@gsb-core/mcp-docs/src/docs/getApiDocs.ts

Documentation for GSB MCP implementations

/**
 * Documentation for the getApiDocs operation
 */

/**
 * Returns documentation for the getApiDocs operation
 * @return {string} markdown documentation
 */
export function getApiDocsDocs(): string {
  return `
# GetApiDocs Operation

## General Description

The \`getApiDocs\` operation provides general information about the GSB Entity Service API.

## Detailed Description

This operation returns basic metadata about the API, including its name, version, and description. Unlike the \`getDocs\` operation, it does not include detailed documentation for individual operations. This is useful when you need a quick overview of the API without the detailed operation documentation.

## Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| token | string | No | Authentication token for your request. If not provided, the system will use the default API key from environment variables. |
| tenantCode | string | No | Tenant code to specify which tenant's data to access. If not provided, the system will extract it from the token or use the default tenant code from environment variables. |

## Response

### Success Response

\`\`\`json
{
    "success": true,
    "data": {
        "name": "GSB Entity Service API",
        "version": "string",
        "description": "API for managing entity data and definitions"
    }
}
\`\`\`

### Error Response

\`\`\`json
{
    "success": false,
    "error": "Error message describing what went wrong"
}
\`\`\`

## Example Usage

### Get API Information

\`\`\`typescript
const result = await getApiDocs({
  token: "your-auth-token"
});

if (result.success) {
  const apiInfo = result.data;
  console.log(\`API Name: \${apiInfo.name}\`);
  console.log(\`Version: \${apiInfo.version}\`);
  console.log(\`Description: \${apiInfo.description}\`);
} else {
  console.error("Error:", result.error);
}
\`\`\`

### Check API Version

\`\`\`typescript
async function checkApiVersion(requiredVersion, token) {
  const result = await getApiDocs({ token });
  
  if (!result.success) {
    console.error("Error checking API version:", result.error);
    return false;
  }
  
  const currentVersion = result.data.version;
  
  // Compare versions (this is a simple string comparison)
  // For more complex version comparisons, consider using a version comparison library
  if (currentVersion === requiredVersion) {
    console.log(\`API version \${currentVersion} matches required version \${requiredVersion}\`);
    return true;
  } else {
    console.warn(\`API version mismatch: current \${currentVersion}, required \${requiredVersion}\`);
    return false;
  }
}

// Usage
const isCompatible = await checkApiVersion("1.0.0", "your-auth-token");
if (!isCompatible) {
  console.warn("This client may not be fully compatible with the current API version");
}
\`\`\`

### Display API Information in UI

\`\`\`typescript
import React, { useEffect, useState } from 'react';

function ApiInfoComponent({ token }) {
  const [apiInfo, setApiInfo] = useState(null);
  const [loading, setLoading] = useState(true);
  const [error, setError] = useState(null);
  
  useEffect(() => {
    async function fetchApiInfo() {
      try {
        const result = await getApiDocs({ token });
        
        if (result.success) {
          setApiInfo(result.data);
        } else {
          setError(result.error);
        }
      } catch (err) {
        setError(err.message);
      } finally {
        setLoading(false);
      }
    }
    
    fetchApiInfo();
  }, [token]);
  
  if (loading) return <div>Loading API information...</div>;
  if (error) return <div>Error: {error}</div>;
  
  return (
    <div className="api-info">
      <h2>{apiInfo.name}</h2>
      <div className="version">Version: {apiInfo.version}</div>
      <p>{apiInfo.description}</p>
    </div>
  );
}

// Usage
<ApiInfoComponent token="your-auth-token" />
\`\`\`

## Additional Information

- The getApiDocs operation provides only general information about the API, not detailed documentation for individual operations.
- For detailed documentation on all operations, use the getDocs operation instead.
- This operation is lightweight and can be used for quick API version checks or displaying basic API information in a user interface.
- The API version information can be useful for client applications to ensure compatibility with the API.
- This operation requires minimal permissions and can typically be called with any valid authentication token.
`;
}

/**
 * Returns a brief summary of the getApiDocs operation.
 * @return {string} A short description of the function.
 */
export function getApiDocsSummary(): string {
  return `
**Purpose**: Retrieves general information about the API service.

**When to use**:
- Checking API version
- Displaying API metadata
- Verifying compatibility
- Getting service overview

**Inputs**:
- token (optional)
- tenantCode (optional)

**Returns**: Basic API metadata (name, version, description).
`;
}

export default getApiDocsDocs;