AgentSkillsCN

OpenAPI Drift Detection

检测 OpenAPI/Swagger 规范与实际处理程序实现之间的偏差——包括遗漏的端点、Schema 不匹配，以及未在文档中明确说明的参数。

SKILL.md
--- frontmatter
name: OpenAPI Drift Detection
description: Detect drift between OpenAPI/Swagger specifications and actual handler implementations — missing endpoints, schema mismatches, undocumented parameters
category: api
version: 1.0.0
triggers:
  - handler-change
  - spec-change
  - new-endpoint
globs: "**/handler/**,**/dto/**,**/swagger/**,**/*.openapi.*"

OpenAPI Drift Detection Skill

Compare the declared OpenAPI specification against actual handler implementations to detect drift, missing documentation, and contract violations.

Trigger Conditions

  • •Handler or controller files change
  • •OpenAPI/Swagger spec files change
  • •New endpoints are added without spec updates
  • •User invokes with "check API drift" or "openapi-drift-detection"

Input Contract

  • •Required: Path to handler directory and OpenAPI spec file
  • •Optional: Path to DTO/request/response definitions

Output Contract

  • •List of endpoints in code but NOT in spec (undocumented)
  • •List of endpoints in spec but NOT in code (stale spec)
  • •Schema mismatches (request/response shape differences)
  • •Missing authentication requirements in spec
  • •Missing error response documentation

Tool Permissions

  • •Read: Handler files, DTO files, OpenAPI/Swagger specs, route configuration
  • •Write: None (read-only analysis)
  • •Search: Grep for route registrations (r.GET, r.POST, etc.), Swagger annotations

Execution Steps

  1. •Extract routes from code: Parse main.go or router files for all registered routes (HTTP method + path)
  2. •Extract routes from spec: Parse OpenAPI/Swagger YAML/JSON for all documented endpoints
  3. •Compare: Find routes in code but not in spec, and routes in spec but not in code
  4. •Schema comparison: For each shared route, compare request/response schemas between code DTOs and spec definitions
  5. •Auth check: Verify all authenticated routes have security requirements in spec
  6. •Report: Produce a drift report with specific file:line references

Success Criteria

  • •Zero undocumented endpoints
  • •Zero stale spec entries
  • •All schemas match between code and spec
  • •All authenticated routes documented as such

References

  • •.cursor/rules/121-route-auth-enforcement.mdc