diff --git a/CHANGELOG.md b/CHANGELOG.md index 6c8b0f4f..7b7b120f 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -11,6 +11,9 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0 - [Zephyr] Added a tool for retrieving Environments [#243](https://github.com/SmartBear/smartbear-mcp/pull/243) - [Zephyr] Added a tool for retrieving a list of Test Executions [#213](https://github.com/SmartBear/smartbear-mcp/pull/213) +- [Swagger] Added `create_api_from_prompt` tool for generating API definitions from natural language descriptions using SmartBear AI, with automatic organization governance (formerly standardization) +- [Swagger] Added `apply_api_governance` (formerly `standardize_api`) tool for scanning and automatically fixing API definitions to comply with organization governance rules using SmartBear AI +- [Swagger] Terminology update: "Standardization" is now marketed as "Governance" - both terms refer to the same feature for API validation and compliance ## [0.11.0] - 2025-11-20 @@ -43,13 +46,13 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0 ### Added - [Qmetry] Added 4 New QMetry tools to enhance test management capabilities [#194](https://github.com/SmartBear/smartbear-mcp/pull/194) - [Qmetry] Implement comprehensive test case tooling with enhanced error handling [#193](https://github.com/SmartBear/smartbear-mcp/pull/193) -- [API Hub] Add `scan_api_standardization` tool for validating API definitions against organization standardization rules [#176](https://github.com/SmartBear/smartbear-mcp/pull/176) +- [API Hub] Add `scan_api_governance` (formerly `scan_api_standardization`) tool for validating API definitions against organization governance rules [#176](https://github.com/SmartBear/smartbear-mcp/pull/176) ## [0.8.0] - 2025-10-13 ### Added -- [API Hub] Add `create_or_update_api` tool for creating or updating new API definitions in API Hub for Design -- [API Hub] Add `create_api_from_template` tool for creating new API definitions from templates in API Hub for Design +- [API Hub] Add `create_or_update_api` tool for creating or updating new API definitions in API Hub for Design [#257](https://github.com/SmartBear/smartbear-mcp/pull/257) +- [API Hub] Add `create_api_from_template` tool for creating new API definitions from templates in API Hub for Design [#257](https://github.com/SmartBear/smartbear-mcp/pull/257) - [Zephyr] Add Zephyr capabilities to MCP [#171](https://github.com/SmartBear/smartbear-mcp/pull/171) ### Changed diff --git a/README.md b/README.md index 52d9a997..08137a04 100644 --- a/README.md +++ b/README.md @@ -32,7 +32,7 @@ See individual guides for suggested prompts and supported tools and resources: - [Test Hub](https://developer.smartbear.com/smartbear-mcp/docs/test-hub-integration) - Test management and execution capabilities - **Swagger** - [Portal](https://developer.smartbear.com/smartbear-mcp/docs/swagger-portal-integration) - Portal and product management capabilities - - [Studio](https://developer.smartbear.com/smartbear-mcp/docs/swagger-studio-integration) - API and Domain management capabilities + - [Studio](https://developer.smartbear.com/smartbear-mcp/docs/swagger-studio-integration) - API and Domain management capabilities, including AI-powered API generation from prompts and automatic governance (formerly standardization) - [Contract Testing (PactFlow)](https://developer.smartbear.com/pactflow/default/getting-started) - Contract testing capabilities - [QMetry](https://developer.smartbear.com/smartbear-mcp/docs/qmetry-integration) - QMetry Test Management capabilities - [Zephyr](https://developer.smartbear.com/smartbear-mcp/docs/zephyr-integration) - Zephyr Test Management capabilities diff --git a/docs/products/SmartBear MCP Server/swagger-studio-integration.md b/docs/products/SmartBear MCP Server/swagger-studio-integration.md index 9f9a125e..2d7c7043 100644 --- a/docs/products/SmartBear MCP Server/swagger-studio-integration.md +++ b/docs/products/SmartBear MCP Server/swagger-studio-integration.md @@ -64,18 +64,48 @@ The Swagger Studio client provides comprehensive API and Domain management capab | `apiName` | API name | string | Yes | | `template` | Template name to use for creating the API. Format: owner/template-name/version (e.g., 'swagger-hub/petstore-template/1.0.0'). API is created with fixed values: private visibility, no project assignment, and reconciliation enabled.
**Note**: Available templates can be found in your organization's SwaggerHub template library or by checking the SwaggerHub public templates (e.g. via search_apis_and_domains). | string | Yes | -#### `scan_api_standardization` +#### `scan_api_governance` (formerly `scan_api_standardization`) -- Purpose: Run a standardization scan against an API definition using the organization's standardization configuration. Validates OpenAPI/AsyncAPI definitions against configured governance rules and style guides. -- Returns: Standardization result with a list of validation errors and warnings. Each error includes severity level, rule name, and location information. +- Purpose: Run a governance scan against an API definition using the organization's governance configuration. Validates OpenAPI/AsyncAPI definitions against configured governance rules and style guides. +- Returns: Governance scan result with a list of validation errors and warnings. Each error includes severity level, rule name, and location information. - Use case: Validate API definitions against organization standards before publishing, ensure compliance with API governance policies, and identify design inconsistencies early in the development process. +- Note: This feature was previously called "standardization" and is now marketed as "governance". Both terms refer to the same functionality. - Parameters: | Parameter | Description | Type | Required | | --- | --- | --- | --- | -| `orgName` | Organization name to use for standardization rules | string | Yes | +| `orgName` | Organization name to use for governance rules | string | Yes | | `definition` | API definition content (OpenAPI/AsyncAPI specification in JSON or YAML format). Format is automatically detected. | string | Yes | +#### `create_api_from_prompt` + +- Purpose: Generate and save an API definition based on a natural language prompt using SmartBear AI. This tool automatically applies organization governance rules during API generation. The specType parameter determines the format of the generated definition. +- Returns: API metadata including owner, name, specType, version (from X-Version header if available), SwaggerHub URL, and operation type ('create' or 'update'). HTTP 201 indicates creation, HTTP 200 indicates update. +- Use case: Rapidly create APIs from natural language descriptions (e.g., "Create a RESTful API for managing a pet store with endpoints for pets, orders, and inventory"), generate API prototypes for proof-of-concept work, or bootstrap new API projects with AI assistance while ensuring compliance with organization standards. +- Note: This tool automatically applies governance rules (previously called "standardization") during API generation. +- Parameters: + +| Parameter | Description | Type | Required | +| --- | --- | --- | --- | +| `owner` | API owner (organization or user, case-sensitive) | string | Yes | +| `apiName` | API name | string | Yes | +| `prompt` | The prompt describing the desired API functionality. Be specific about resources, operations, and data models. Examples: "Create a RESTful API for managing a pet store with endpoints for pets, orders, and inventory", "Build an API for a blog platform with posts, comments, and users" | string | Yes | +| `specType` | Specification type for the generated API definition.
Options: `openapi20` (OpenAPI 2.0), `openapi30x` (OpenAPI 3.0.x, default), `openapi31x` (OpenAPI 3.1.x), `asyncapi2xx` (AsyncAPI 2.x), `asyncapi30x` (AsyncAPI 3.0.x)
Default: `openapi30x` | string | No | + +#### `apply_api_governance` (formerly `standardize_api`) + +- Purpose: Apply governance rules and fix an API definition using AI. Scans the API definition for governance violations and automatically fixes them using SmartBear AI. If violations are found, they will be sent to SmartBear AI to generate a corrected definition, which is then saved back to the registry. +- Returns: Governance result including a message, the number of errors found, and the fixed definition if successful. Also includes details about each error (description, line number, severity). +- Use case: Automatically fix API definitions that fail governance scans, remediate governance violations in existing APIs, or clean up imported/legacy API definitions to meet current organization standards. +- Note: This feature was previously called "standardization" and is now marketed as "governance". Both terms refer to the same functionality. +- Parameters: + +| Parameter | Description | Type | Required | +| --- | --- | --- | --- | +| `owner` | API owner (organization or user, case-sensitive) | string | Yes | +| `api` | API name (case-sensitive) | string | Yes | +| `version` | Version identifier | string | Yes | + ## Configuration To use Swagger Studio tools, you need to configure the `SWAGGER_API_KEY` environment variable with your Swagger API token. @@ -84,5 +114,6 @@ To use Swagger Studio tools, you need to configure the `SWAGGER_API_KEY` environ 1. **API Discovery**: Use `search_apis_and_domains` to find existing APIs in your Swagger Studio. 2. **API Integration**: Retrieve specific API definitions with `get_api_definition` for development or testing purposes. -3. **API Creation**: Create new APIs using `create_or_update_api` with custom definitions or `create_api_from_template` using organization templates. -4. **API Governance**: Validate API definitions against organization standards using `scan_api_standardization` to ensure compliance with governance policies. +3. **API Creation**: Create new APIs using `create_or_update_api` with custom definitions, `create_api_from_template` using organization templates, or `create_api_from_prompt` with natural language descriptions powered by AI. +4. **API Governance**: Validate API definitions against organization standards using `scan_api_governance` (formerly `scan_api_standardization`) to ensure compliance with governance policies, then use `apply_api_governance` (formerly `standardize_api`) to automatically fix any violations. +5. **AI-Powered API Development**: Leverage `create_api_from_prompt` to rapidly prototype APIs from natural language, then use `apply_api_governance` (formerly `standardize_api`) to ensure they meet your organization's standards. diff --git a/src/swagger/client.ts b/src/swagger/client.ts index 50642cd1..9eb18b28 100644 --- a/src/swagger/client.ts +++ b/src/swagger/client.ts @@ -12,6 +12,8 @@ import { type ApiDefinitionParams, type ApiSearchParams, type ApiSearchResponse, + type CreateApiFromPromptParams, + type CreateApiFromPromptResponse, type CreateApiFromTemplateParams, type CreateApiFromTemplateResponse, type CreateApiParams, @@ -34,6 +36,8 @@ import { type ScanStandardizationParams, type SectionsListResponse, type StandardizationResult, + type StandardizeApiParams, + type StandardizeApiResponse, type SuccessResponse, SwaggerAPI, SwaggerConfiguration, @@ -223,12 +227,24 @@ export class SwaggerClient implements Client { return this.getApi().getOrganizations(args); } + async createApiFromPrompt( + args: CreateApiFromPromptParams, + ): Promise { + return this.getApi().createApiFromPrompt(args); + } + async scanStandardization( args: ScanStandardizationParams, ): Promise { return this.getApi().scanStandardization(args); } + async standardizeApi( + args: StandardizeApiParams, + ): Promise { + return this.getApi().standardizeApi(args); + } + registerTools( register: RegisterToolsFunction, _getInput: GetInputFunction, diff --git a/src/swagger/client/api.ts b/src/swagger/client/api.ts index 21424f87..c696fe64 100644 --- a/src/swagger/client/api.ts +++ b/src/swagger/client/api.ts @@ -30,12 +30,16 @@ import type { ApiSearchResponse, ApiSpecification, ApisJsonResponse, + CreateApiFromPromptParams, + CreateApiFromPromptResponse, CreateApiFromTemplateParams, CreateApiFromTemplateResponse, CreateApiParams, CreateApiResponse, ScanStandardizationParams, StandardizationResult, + StandardizeApiParams, + StandardizeApiResponse, } from "./registry-types.js"; import type { OrganizationsListResponse, @@ -52,6 +56,33 @@ import type { const SWAGGER_URL_REGEX = /\/(apis|domains|templates)\/([^/]+)\/([^/]+)\/([^/]+)/; +/** + * Type guard to check if a value has an 'id' property + */ +function hasId( + value: unknown, +): value is { id: string } & Record { + return typeof value === "object" && value !== null && "id" in value; +} + +/** + * Type guard to check if a value has a 'message' property + */ +function hasMessage( + value: unknown, +): value is { message: string } & Record { + return typeof value === "object" && value !== null && "message" in value; +} + +/** + * Type guard to check if a value has an 'errorsFound' property + */ +function hasErrorsFound( + value: unknown, +): value is { errorsFound: number } & Record { + return typeof value === "object" && value !== null && "errorsFound" in value; +} + export class SwaggerAPI { private config: SwaggerConfiguration; private headers: Record; @@ -188,7 +219,7 @@ export class SwaggerAPI { body: JSON.stringify(body), }); const result = await this.handleResponse(response); - if (!("id" in (result as any))) { + if (!hasId(result)) { throw new Error("Unexpected empty response creating portal"); } return result as Portal; @@ -203,7 +234,7 @@ export class SwaggerAPI { }, ); const result = await this.handleResponse(response); - if (!("id" in (result as any))) { + if (!hasId(result)) { throw new ToolError("Portal not found or empty response"); } return result as Portal; @@ -269,7 +300,7 @@ export class SwaggerAPI { }, ); const result = await this.handleResponse(response); - if (!("id" in (result as any))) { + if (!hasId(result)) { throw new Error("Unexpected empty response creating product"); } return result as Product; @@ -284,7 +315,7 @@ export class SwaggerAPI { }, ); const result = await this.handleResponse(response); - if (!("id" in (result as any))) { + if (!hasId(result)) { throw new ToolError("Product not found or empty response"); } return result as Product; @@ -738,7 +769,7 @@ export class SwaggerAPI { owner: params.owner, apiName: params.apiName, version: "1.0.0", - url: `https://app.swaggerhub.com/apis/${params.owner}/${params.apiName}/1.0.0`, + url: `${this.config.uiBasePath}/apis/${params.owner}/${params.apiName}/1.0.0`, operation, }; } @@ -782,7 +813,61 @@ export class SwaggerAPI { owner: params.owner, apiName: params.apiName, template: params.template, - url: `https://app.swaggerhub.com/apis/${params.owner}/${params.apiName}`, + url: `${this.config.uiBasePath}/apis/${params.owner}/${params.apiName}`, + operation, + }; + } + + /** + * Create API from Prompt using SmartBear AI + * @param params Parameters for creating API from prompt including owner, api name, prompt, and specification type + * @returns Created API metadata with URL. HTTP 201 indicates creation, HTTP 200 for update, HTTP 205 for reload + */ + async createApiFromPrompt( + params: CreateApiFromPromptParams, + ): Promise { + // Construct the URL with query parameters + const searchParams = new URLSearchParams(); + const specType = params.specType ?? "openapi30x"; + searchParams.append("specType", specType); + + const url = `${this.config.registryBasePath}/apis/${encodeURIComponent( + params.owner, + )}/${encodeURIComponent(params.apiName)}/.ai?${searchParams.toString()}`; + + // Use POST method with JSON body containing the prompt + const response = await fetch(url, { + method: "POST", + headers: { + ...this.headers, + "Content-Type": "application/json", + }, + body: JSON.stringify(params.prompt), + }); + + if (!response.ok) { + const errorText = await response.text().catch(() => ""); + throw new ToolError( + `SwaggerHub Registry API createApiFromPrompt failed - status: ${response.status} ${response.statusText}${errorText ? ` - ${errorText}` : ""}. URL: ${url}`, + ); + } + + // Determine operation type based on HTTP status code + // 201 = new API created, 200 = existing API updated, 205 = API saved and should be reloaded + const operation = response.status === 201 ? "create" : "update"; + + // Extract version from X-Version header + const version = response.headers.get("X-Version"); + + // Return formatted response with the required fields + return { + owner: params.owner, + apiName: params.apiName, + specType: specType, + version: version || undefined, + url: version + ? `${this.config.uiBasePath}/apis/${params.owner}/${params.apiName}/${version}` + : `${this.config.uiBasePath}/apis/${params.owner}/${params.apiName}`, operation, }; } @@ -830,7 +915,7 @@ export class SwaggerAPI { const parsedDefinition = JSON.parse(params.definition); requestBody = JSON.stringify(parsedDefinition); } catch (error) { - throw new Error( + throw new ToolError( `Invalid JSON format in definition: ${ error instanceof Error ? error.message : "Unknown error" }`, @@ -853,11 +938,54 @@ export class SwaggerAPI { if (!response.ok) { const errorText = await response.text().catch(() => ""); - throw new Error( + throw new ToolError( `SwaggerHub Registry API scanStandardization failed - status: ${response.status} ${response.statusText}${errorText ? ` - ${errorText}` : ""}. URL: ${url}`, ); } return await this.handleResponse(response); } + + /** + * Standardize and fix an API definition using AI + * @param params Parameters including owner, API name, and version + * @returns Standardization response with status and fixed definition + */ + async standardizeApi( + params: StandardizeApiParams, + ): Promise { + const url = `${this.config.registryBasePath}/apis/${encodeURIComponent( + params.owner, + )}/${encodeURIComponent(params.api)}/${encodeURIComponent( + params.version, + )}/standardize`; + + const response = await fetch(url, { + method: "POST", + headers: this.headers, + }); + + if (!response.ok) { + const errorText = await response.text().catch(() => ""); + throw new ToolError( + `SwaggerHub Registry API standardizeApi failed - status: ${response.status} ${response.statusText}${errorText ? ` - ${errorText}` : ""}. URL: ${url}`, + ); + } + + const result = await this.handleResponse(response); + + // Validate that we have the expected response structure + if (!hasMessage(result)) { + throw new ToolError( + "Unexpected response format from standardizeApi endpoint", + ); + } + + // If errorsFound is not present, default to 0 (no errors found) + if (!hasErrorsFound(result)) { + return { ...result, errorsFound: 0 } as StandardizeApiResponse; + } + + return result as StandardizeApiResponse; + } } diff --git a/src/swagger/client/configuration.ts b/src/swagger/client/configuration.ts index 71f3a8e7..d7b541fe 100644 --- a/src/swagger/client/configuration.ts +++ b/src/swagger/client/configuration.ts @@ -2,6 +2,7 @@ export interface SwaggerConfigurationParameters { token: string; // API auth token (required) portalBasePath?: string; // Base path for Portal API requests registryBasePath?: string; // Base path for Registry API requests + uiBasePath?: string; // Base URL for the SwaggerHub UI userManagementBasePath?: string; // Base path for User Management API requests headers?: Record; // Additional headers for API requests } @@ -10,6 +11,7 @@ export class SwaggerConfiguration { token: string; portalBasePath: string; registryBasePath: string; + uiBasePath: string; userManagementBasePath: string; headers: Record; @@ -18,7 +20,8 @@ export class SwaggerConfiguration { this.portalBasePath = param.portalBasePath || "https://api.portal.swaggerhub.com/v1"; this.registryBasePath = - param.registryBasePath || "https://api.swaggerhub.com"; + param.registryBasePath || "https://api.swaggerhub.com"; // Default for registry API + this.uiBasePath = param.uiBasePath || "https://app.swaggerhub.com"; // Default for UI this.userManagementBasePath = param.userManagementBasePath || "https://api.swaggerhub.com/user-management/v1"; diff --git a/src/swagger/client/registry-types.ts b/src/swagger/client/registry-types.ts index 8c01f475..4a62f1e7 100644 --- a/src/swagger/client/registry-types.ts +++ b/src/swagger/client/registry-types.ts @@ -95,6 +95,38 @@ export const ScanStandardizationParamsSchema = z.object({ ), }); +export const CreateApiFromPromptParamsSchema = z.object({ + owner: z + .string() + .describe("API owner (organization or user, case-sensitive)"), + apiName: z.string().describe("API name"), + prompt: z + .string() + .describe( + "The prompt describing the desired API functionality (e.g., 'Create a RESTful API for managing a pet store with endpoints for pets, orders, and inventory')", + ), + specType: z + .enum([ + "openapi20", + "openapi30x", + "openapi31x", + "asyncapi2xx", + "asyncapi30x", + ]) + .default("openapi30x") + .describe( + "Specification type for the generated API definition. Use: 'openapi20' for OpenAPI 2.0, 'openapi30x' for OpenAPI 3.0.x (default), 'openapi31x' for OpenAPI 3.1.x, 'asyncapi2xx' for AsyncAPI 2.x, 'asyncapi30x' for AsyncAPI 3.0.x", + ), +}); + +export const StandardizeApiParamsSchema = z.object({ + owner: z + .string() + .describe("API owner (organization or user, case-sensitive)"), + api: z.string().describe("API name (case-sensitive)"), + version: z.string().describe("Version identifier"), +}); + // Registry API types for SwaggerHub Design functionality - generated from Zod schemas export type ApiSearchParams = z.infer; export type ApiDefinitionParams = z.infer; @@ -105,6 +137,10 @@ export type CreateApiFromTemplateParams = z.infer< export type ScanStandardizationParams = z.infer< typeof ScanStandardizationParamsSchema >; +export type CreateApiFromPromptParams = z.infer< + typeof CreateApiFromPromptParamsSchema +>; +export type StandardizeApiParams = z.infer; // APIs.json format response types export interface ApiProperty { @@ -167,7 +203,29 @@ export interface CreateApiFromTemplateResponse { operation: "create" | "update"; } +// Response type for API created from prompt +export interface CreateApiFromPromptResponse { + owner: string; + apiName: string; + specType: string; + version?: string; // Version from X-Version header + url: string; + operation: "create" | "update"; +} + // Response type for standardization scan export interface StandardizationResult { [key: string]: unknown; // The API returns standardization errors/results } + +// Response type for API standardization +export interface StandardizeApiResponse { + message: string; + errorsFound: number; + fixedDefinition?: string; + errors?: Array<{ + description: string; + line?: number; + severity?: string; + }>; +} diff --git a/src/swagger/client/tools.ts b/src/swagger/client/tools.ts index 28b9132d..7c733622 100644 --- a/src/swagger/client/tools.ts +++ b/src/swagger/client/tools.ts @@ -26,9 +26,11 @@ import { import { ApiDefinitionParamsSchema, ApiSearchParamsSchema, + CreateApiFromPromptParamsSchema, CreateApiFromTemplateParamsSchema, CreateApiParamsSchema, ScanStandardizationParamsSchema, + StandardizeApiParamsSchema, } from "./registry-types.js"; import { OrganizationsQuerySchema } from "./user-management-types.js"; @@ -197,10 +199,24 @@ export const TOOLS: SwaggerToolParams[] = [ handler: "getOrganizations", }, { - title: "Scan API Standardization", + title: "Scan API Governance", summary: - "Run a standardization scan against an API definition using the organization's standardization configuration. Accepts a YAML or JSON OpenAPI/AsyncAPI definition and returns a list of standardization errors and validation issues.", + "Run a governance scan against an API definition using the organization's governance configuration. Validates API definitions against configured governance rules and style guides. Accepts a YAML or JSON OpenAPI/AsyncAPI definition and returns a list of governance errors and validation issues. Note: Governance was previously called 'standardization' - both terms refer to the same feature.", inputSchema: ScanStandardizationParamsSchema, handler: "scanStandardization", }, + { + title: "Create API from Prompt using SmartBear AI", + summary: + "Generate and save an API definition based on a prompt using SmartBear AI. This tool automatically applies organization governance rules during API generation. The specType parameter determines the format of the generated definition. Use: 'openapi20' for OpenAPI 2.0, 'openapi30x' for OpenAPI 3.0.x, 'openapi31x' for OpenAPI 3.1.x, 'asyncapi2xx' for AsyncAPI 2.x, 'asyncapi30x' for AsyncAPI 3.0.x. Use this tool when creating APIs with organization governance rules or when generating APIs from natural language descriptions. Note: Governance was previously called 'standardization'. Returns HTTP 201 for creation, HTTP 200 for update. Response includes 'operation' field indicating whether it was a 'create' or 'update' operation along with API details and SwaggerHub URL.", + inputSchema: CreateApiFromPromptParamsSchema, + handler: "createApiFromPrompt", + }, + { + title: "Apply API Governance Rules", + summary: + "Apply governance rules and fix an API definition using AI. Scans the API definition for governance violations and automatically fixes them using SmartBear AI. If violations are found, they will be sent to SmartBear AI to generate a corrected definition, which is then saved back to the registry. Returns the number of errors found and the fixed definition if successful. Note: Governance was previously called 'standardization' - both terms refer to the same feature.", + inputSchema: StandardizeApiParamsSchema, + handler: "standardizeApi", + }, ];