Developer Documentation & API Visibility Audit

Audit technical documentation, API reference portals, OpenAPI/Swagger specifications, and developer guides to ensure AI coding agents (Claude Code, Cursor, Copilot, Antigravity) and search engines can discover, understand, and generate accurate code against your APIs without hallucination.

Workflow

1. Discover Machine-Readable API Schemas:

   • Probe conventional schema paths: /openapi.json, /openapi.yaml, /swagger.json, /.well-known/openapi.json, and <link rel="describedby"> header/HTML tags [OPENAPI-SPEC-01].
   • Verify whether schema files return 200 OK with valid JSON/YAML syntax and parseable paths, parameters, requestBody, and responses definitions.

2. Audit Server-Side Rendering (SSR) of Reference Pages:

   • Fetch raw HTML (curl -s "$URL") and verify whether HTTP methods (GET, POST, PUT, DELETE), endpoint paths, parameter descriptions, and error codes exist in the initial HTML payload [OPENAPI-SPEC-01].
   • Flag client-side-only SPA doc frameworks (e.g. bare React/Redoc/Swagger UI shells) that deliver an empty <div id="swagger-ui"></div> to non-JavaScript AI crawlers.

3. Verify Code Sample Formatting & Language Tagging:

   • Inspect code blocks for CommonMark / GFM language info strings (<pre><code class="language-typescript">, <pre><code class="language-python">) [COMMONMARK-CODE-01].
   • Flag untagged code blocks (<pre><code> with no language class) or obfuscated tabbed interfaces that prevent AI models from parsing sample syntax.