Agent Mode Queries API Catalog and Fixes Spec Issues

Quick Overview

The agent mode successfully resolved 30 lint warnings in the user-permissions OpenAPI specification by generating a fixed YAML file, updating the corresponding Postman collection structure, and validating the fix by running API tests which passed successfully.

Key Points: The agent mode fixed 30 lint warnings identified in the user-permissions OpenAPI spec (userpermissions.api.yaml), which were causing governance compliance issues. The fix involved generating a complete fixed YAML file which was then used to update the Postman collection structure (User Permissions API.postmancollection.json). The user requested fixes for lint warnings and updates to the backend code (server.js) and collection structure. The quality summary showed an 'Excellent' overall score (A) before the process, with governance issues stemming from the lint warnings. After updating the spec and collection, Postman API tests were run, showing success across all steps, including 'Lint API Specification', confirming the fixes. The speaker noted that the documentation was updated to reflect changes like removing an endpoint and updating response formats. The process concluded with committing the changes to the GitHub repository and closing the associated pull request.

Context: The video demonstrates the use of an AI agent (Claude Opus 4.5) in a development workflow to address quality issues identified in an API specification (OpenAPI/YAML) for a service named 'user-permissions'. The initial quality check highlighted 30 lint warnings related to governance best practices, which the agent was tasked to resolve by fixing the specification and updating related assets like a Postman collection.

Detailed Analysis

The demonstration begins by examining the Quality Summary for the 'user-permissions' service, which achieved an 'Excellent' score (A) but flagged 30 lint warnings in the spec file (userpermissions.api.yaml) as an area of concern impacting API governance best practices. The user prompts the agent to fix these 30 lint warnings. The agent first generates the complete fixed YAML file, detailing exactly which lines were changed to resolve the warnings, such as updating inline schemas to use reusable components (e.g., resolving issues on lines 147, 178, 185, 190, 209, 210). The agent then updates the Postman collection by suggesting the user update their local collection file to match the fixed spec. The agent also updates the backend (server.js) to align with the updated specification, including changes to endpoint handling, response formats, and removing an obsolete endpoint. Finally, the user commits these changes to the 'simple-spec-linting' branch, merges the pull request, and runs the Postman API tests in the CI pipeline. The CI run, which includes a 'Lint API Specification' step, shows success with 'No issues found', confirming the agent's fixes resolved the initial governance warnings.