--- title: "API Discovery and Documentation at the Gateway: Inventory, Ownership, and Drift - API7.ai" description: "Use gateway state as discovery evidence, reconcile it with contracts and ownership, and publish documentation that tracks deployed API lifecycle." url: "https://api7.ai/learning-center/api-gateway-guide/api-discovery-documentation-gateway" --- [Skip to article](#column-content) Column contentsAPI Gateway Guide [API Gateway Guide](https://api7.ai/learning-center/api-gateway-guide) Search this column 01 Gateway Fundamentals [View this topic · 10](https://api7.ai/learning-center/api-gateway-guide?topic=fundamentals)[1. What Is an API Gateway? API Gateway Software and Use Cases](https://api7.ai/learning-center/api-gateway-guide/what-is-an-api-gateway)[2. Why Do Modern Architectures Need an API Gateway?](https://api7.ai/learning-center/api-gateway-guide/why-do-modern-architectures-need-api-gateway)[3. Reverse Proxy vs Load Balancer vs API Gateway](https://api7.ai/learning-center/api-gateway-guide/api-gateway-vs-reverse-proxy-vs-load-balancer)[4. API Gateway and Microservices: Decoupling and Traffic Management](https://api7.ai/learning-center/api-gateway-guide/api-gateway-and-microservices)[5. Understanding Core API Gateway Features](https://api7.ai/learning-center/api-gateway-guide/core-api-gateway-features)[6. Open Source vs. Commercial API Gateways: How to Choose the Right One?](https://api7.ai/learning-center/api-gateway-guide/open-source-vs-commercial-api-gateway)[7. API Gateway vs Service Mesh: How to Choose?](https://api7.ai/learning-center/api-gateway-guide/api-gateway-vs-service-mesh)[8. Envoy vs NGINX, Java, and Go for API Gateways](https://api7.ai/learning-center/api-gateway-guide/nginx-vs-envoy-vs-java-vs-go)[9. Core Concepts of API Gateway: Service, Route, Upstream, Plugin, and Consumer](https://api7.ai/learning-center/api-gateway-guide/core-concepts-of-api-gateway)[10. API Gateway Comparison: Apache APISIX vs. Kong vs. Traefik vs. KrakenD vs. Tyk](https://api7.ai/learning-center/api-gateway-guide/api-gateway-comparison-apisix-kong-traefik-krakend-tyk) 02 Gateway Architecture and Design [View this topic · 10](https://api7.ai/learning-center/api-gateway-guide?topic=architecture)[11. Deep Dive into API Gateway Architecture: Core Components and Design Principles](https://api7.ai/learning-center/api-gateway-guide/api-gateway-architecture)[12. Choosing the Right API Gateway for Your Architecture](https://api7.ai/learning-center/api-gateway-guide/api-gateway-monolithic-vs-microservices)[13. How to Architect an API Gateway for High Availability (HA)?](https://api7.ai/learning-center/api-gateway-guide/api-gateway-high-availability)[14. API Gateway Plugin Architecture: How to Extend and Customize Your API Gateway](https://api7.ai/learning-center/api-gateway-guide/api-gateway-plugin-system)[15. How Event-Driven Architecture (EDA) Works with API Gateway?](https://api7.ai/learning-center/api-gateway-guide/api-gateway-event-driven-architecture)[16. API Gateway Request Lifecycle Explained](https://api7.ai/learning-center/api-gateway-guide/api-gateway-request-lifecycle-explained)[17. Cloud-Native API Gateway on Kubernetes](https://api7.ai/learning-center/api-gateway-guide/cloud-native-api-gateway-kubernetes)[18. API Gateway Control Plane vs. Data Plane](https://api7.ai/learning-center/api-gateway-guide/api-gateway-control-plane-vs-data-plane)[19. How API Gateways Work with GitOps: Automating API Management](https://api7.ai/learning-center/api-gateway-guide/api-gateway-gitops-integration)[20. How to Perform A/B Testing and Canary Releases with an API Gateway](https://api7.ai/learning-center/api-gateway-guide/ab-testing-canary-release-api-gateway) 03 Gateway Setup and Traffic Handling [View this topic · 10](https://api7.ai/learning-center/api-gateway-guide?topic=traffic-protocols)[21. How to Deploy an API Gateway on Kubernetes: Step-by-Step Guide for Engineers](https://api7.ai/learning-center/api-gateway-guide/deploy-api-gateway-on-kubernetes)[22. Hands-on Setup with Apache APISIX API Gateway](https://api7.ai/learning-center/api-gateway-guide/api-gateway-getting-started-guide)[23. API Gateway Auth: OAuth 2.0, JWT & OIDC with APISIX](https://api7.ai/learning-center/api-gateway-guide/api-gateway-authentication-apache-apisix-oauth-jwt-oidc)[24. Mastering Traffic Control: Efficiently Managing API Requests with Gateways](https://api7.ai/learning-center/api-gateway-guide/api-gateway-traffic-control-strategies)[25. Building Reliable API Gateways with Logging and Monitoring](https://api7.ai/learning-center/api-gateway-guide/api-gateway-logging-monitoring-best-practices)[26. Dynamic Routing in API Gateways: Best Practices for Flexible Traffic Management](https://api7.ai/learning-center/api-gateway-guide/api-gateway-dynamic-routing-management)[27. How API Gateways Support WebSocket](https://api7.ai/learning-center/api-gateway-guide/how-api-gateways-support-websocket)[28. API Gateway for GraphQL: Security, Cost, and Caching](https://api7.ai/learning-center/api-gateway-guide/api-gateway-handle-graphql)[29. How API Gateways Handle HTTP/3 QUIC Requests](https://api7.ai/learning-center/api-gateway-guide/api-gateway-http3-quic)[30. How API Gateways Handle MQTT Requests](https://api7.ai/learning-center/api-gateway-guide/api-gateway-mqtt) 04 Gateway Integrations, AI, and MCP [View this topic · 10](https://api7.ai/learning-center/api-gateway-guide?topic=ai-mcp)[31. How API Gateways Handle gRPC Requests](https://api7.ai/learning-center/api-gateway-guide/api-gateway-grpc-support)[32. How API Gateways Implement Custom Plugins](https://api7.ai/learning-center/api-gateway-guide/api-gateway-custom-plugins)[33. How API Gateways Integrate with Kafka](https://api7.ai/learning-center/api-gateway-guide/api-gateway-kafka-integration)[34. How to Implement API Aggregation in API Gateways](https://api7.ai/learning-center/api-gateway-guide/api-gateway-api-aggregation)[35. How API Gateways Enable Serverless Architecture](https://api7.ai/learning-center/api-gateway-guide/api-gateway-serverless-architecture)[36. How API Gateways Proxy LLM Requests](https://api7.ai/learning-center/api-gateway-guide/api-gateway-proxy-llm-requests)[37. How API Gateways Enhance MCP Servers](https://api7.ai/learning-center/api-gateway-guide/api-gateway-enhance-mcp-server)[38. MCP Gateway vs MCP Proxy vs AI Gateway vs API Gateway](https://api7.ai/learning-center/api-gateway-guide/ai-gateway-vs-mcp-gateway-vs-api-gateway)[39. What Is an AI Gateway? Architecture and Benefits](https://api7.ai/learning-center/api-gateway-guide/what-is-an-ai-gateway)[40. What Is an MCP Gateway? Architecture, Use Cases & How It Works (2026 Guide)](https://api7.ai/learning-center/api-gateway-guide/what-is-mcp-gateway) 05 Gateway Performance [View this topic · 10](https://api7.ai/learning-center/api-gateway-guide?topic=performance)[41. How API Gateway Reduces Latency: Performance Optimization Strategies](https://api7.ai/learning-center/api-gateway-guide/how-api-gateway-reduces-latency)[42. API Gateway Caching Strategy: Comprehensive Analysis and Implementation Guide](https://api7.ai/learning-center/api-gateway-guide/api-gateway-caching-strategy-analysis)[43. How to Optimize API Gateway Load Balancing: Advanced Strategies and Best Practices](https://api7.ai/learning-center/api-gateway-guide/how-to-optimize-api-gateway-load-balancing)[44. How API Gateway Efficiently Handles Large-Scale Traffic: Architecture and Strategies](https://api7.ai/learning-center/api-gateway-guide/how-api-gateway-handles-large-scale-traffic)[45. How to Improve API Gateway QoS: Traffic Classes, Capacity Protection, and SLOs](https://api7.ai/learning-center/api-gateway-guide/api-gateway-quality-of-service)[46. API Gateway Log Storage: Pipelines, Retention, Security, and Cost](https://api7.ai/learning-center/api-gateway-guide/api-gateway-log-storage)[47. API Gateway Timeouts and Retries: Safe Policies and APISIX Configuration](https://api7.ai/learning-center/api-gateway-guide/api-gateway-timeouts-retries)[48. API Gateway Concurrency Control: Capacity Budgets, Backpressure, and Load Shedding](https://api7.ai/learning-center/api-gateway-guide/api-gateway-concurrency-control)[49. Asynchronous API Gateway Patterns: Queues, Callbacks, and Performance Boundaries](https://api7.ai/learning-center/api-gateway-guide/asynchronous-api-gateway-patterns)[50. API Gateway TLS Performance: Handshakes, Session Reuse, and Measurement](https://api7.ai/learning-center/api-gateway-guide/api-gateway-tls-performance) 06 Gateway Security [View this topic · 10](https://api7.ai/learning-center/api-gateway-guide?topic=security)[51. DDoS Defense at the API Gateway: Layered Controls and Failure Planning](https://api7.ai/learning-center/api-gateway-guide/api-gateway-ddos-defense)[52. Distributed API Gateway Rate Limiting: Local vs Redis Counters and Accuracy Trade-offs](https://api7.ai/learning-center/api-gateway-guide/distributed-api-gateway-rate-limiting)[53. API Gateway IP Allowlist and Denylist Management: Trust, Proxies, and Operations](https://api7.ai/learning-center/api-gateway-guide/api-gateway-ip-allowlist-denylist-management)[54. API Gateway Security Scanning: What to Test and How to Operationalize Findings](https://api7.ai/learning-center/api-gateway-guide/api-gateway-security-scanning)[55. SQL Injection and XSS at the API Gateway: Detection Limits and Defense in Depth](https://api7.ai/learning-center/api-gateway-guide/sql-injection-xss-api-gateway)[56. API Access Log Auditing: Evidence, Integrity, Retention, and Review](https://api7.ai/learning-center/api-gateway-guide/api-access-log-auditing)[57. Preventing API Scraping and Abuse: Identity, Behavioral Signals, and Rate Controls](https://api7.ai/learning-center/api-gateway-guide/prevent-api-scraping-abuse)[58. API Gateway mTLS: Client Identity, Certificate Rotation, and APISIX Configuration](https://api7.ai/learning-center/api-gateway-guide/api-gateway-mtls)[59. Fine-Grained API Gateway Authorization: RBAC, ABAC, and External Policy Decisions](https://api7.ai/learning-center/api-gateway-guide/fine-grained-api-gateway-authorization)[60. API Gateway and WAF Reference Architecture: Ownership, Header Trust, and Failure Modes](https://api7.ai/learning-center/api-gateway-guide/api-gateway-waf-reference-architecture) 07 Gateway Ecosystem and Comparisons [View this topic · 10](https://api7.ai/learning-center/api-gateway-guide?topic=ecosystem)[61. Apache APISIX vs Kong: Migration, Operations, and Team Fit](https://api7.ai/learning-center/api-gateway-guide/apache-apisix-vs-kong)[62. Traefik vs Kong vs APISIX: A Reproducible API Gateway Benchmark Method](https://api7.ai/learning-center/api-gateway-guide/traefik-kong-apisix-benchmark-method)[63. Amazon API Gateway Explained: Deployment Models, Trade-offs, and Use Cases](https://api7.ai/learning-center/api-gateway-guide/amazon-api-gateway-explained)[64. API Gateway and Istio: Clear North-South and East-West Boundaries](https://api7.ai/learning-center/api-gateway-guide/api-gateway-istio)[65. API Gateway with NGINX: Layering, Ownership, and Migration Patterns](https://api7.ai/learning-center/api-gateway-guide/api-gateway-nginx)[66. API Gateway with Envoy: Deployment Patterns and Policy Ownership](https://api7.ai/learning-center/api-gateway-guide/api-gateway-envoy)[67. API Gateway with Cloudflare API Shield: Edge and Origin Security Boundaries](https://api7.ai/learning-center/api-gateway-guide/api-gateway-cloudflare-api-shield)[68. Apigee vs MuleSoft vs Amazon API Gateway: A Decision Framework](https://api7.ai/learning-center/api-gateway-guide/apigee-mulesoft-amazon-api-gateway)[69. Should an API Gateway Connect Directly to a Database? Patterns and Risks](https://api7.ai/learning-center/api-gateway-guide/api-gateway-database-access-patterns)[70. API Gateway Architecture for Large-Scale SaaS Platforms](https://api7.ai/learning-center/api-gateway-guide/api-gateway-large-scale-saas-architecture) 08 Industry Applications and Integrations [View this topic · 10](https://api7.ai/learning-center/api-gateway-guide?topic=applications)[71. API Gateway CI/CD: Validation, Promotion, and Safe Rollback](https://api7.ai/learning-center/api-gateway-guide/api-gateway-ci-cd)[72. API Gateways for AI and ML Inference: Traffic, Security, and Observability](https://api7.ai/learning-center/api-gateway-guide/api-gateways-ai-ml-inference)[73. API Gateway Architecture for Financial Services: Controls and Failure Boundaries](https://api7.ai/learning-center/api-gateway-guide/api-gateway-financial-services)[74. API Gateway Architecture for E-Commerce: Checkout Reliability and Traffic Peaks](https://api7.ai/learning-center/api-gateway-guide/api-gateway-ecommerce)[75. API Gateways for Mobile Applications: Authentication, Payloads, and Versioning](https://api7.ai/learning-center/api-gateway-guide/api-gateways-mobile-applications)[76. API Gateways for Web3 Applications: RPC Traffic, Identity, and Abuse Controls](https://api7.ai/learning-center/api-gateway-guide/api-gateways-web3-applications)[77. OpenAPI-Driven API Gateway Operations: Import, Validation, and Drift Control](https://api7.ai/learning-center/api-gateway-guide/openapi-driven-api-gateway-operations)[78. gRPC-Web and gRPC Transcoding Through an API Gateway](https://api7.ai/learning-center/api-gateway-guide/grpc-web-grpc-transcoding-api-gateway)[79. API Gateway Pricing and Cost Optimization: A Workload-Based Model](https://api7.ai/learning-center/api-gateway-guide/api-gateway-pricing-cost-optimization)[80. Evaluating API Gateway Directions: Evidence and Architectural Impact](https://api7.ai/learning-center/api-gateway-guide/api-gateway-trends) 09 Advanced Gateway Applications [View this topic · 10](https://api7.ai/learning-center/api-gateway-guide?topic=operations)[81. API Gateways in Zero Trust Architecture: Identity, Policy, and Limits](https://api7.ai/learning-center/api-gateway-guide/api-gateways-zero-trust-architecture)[82. API Gateway Log Analytics: Correlation, Queries, and Operational Signals](https://api7.ai/learning-center/api-gateway-guide/api-gateway-log-analytics)[83. From API Sprawl to Governed Delivery: The Gateway's Role in Modernization](https://api7.ai/learning-center/api-gateway-guide/api-gateway-modernization)[84. API Monetization at the Gateway: Plans, Metering, Entitlements, and Billing Boundaries](https://api7.ai/learning-center/api-gateway-guide/api-monetization-gateway)[85. Safe AI-Assisted API Gateway Optimization: Recommendations, Guardrails, and Approval](https://api7.ai/learning-center/api-gateway-guide/ai-assisted-api-gateway-optimization)[86. API Gateways for Low-Code and No-Code Integration: Governance and Safety](https://api7.ai/learning-center/api-gateway-guide/api-gateways-low-code-no-code-integration)[87. API Gateway and CIAM Integration: Token Validation, Consent, and Identity Context](https://api7.ai/learning-center/api-gateway-guide/api-gateway-ciam-integration)[88. Elastic API Gateway Scaling: Signals, Capacity, and Safe Scale-In](https://api7.ai/learning-center/api-gateway-guide/elastic-api-gateway-scaling)[89. Multi-Tenant SaaS API Gateways: Isolation, Quotas, and Tenant-Aware Policy](https://api7.ai/learning-center/api-gateway-guide/multi-tenant-saas-api-gateway-policy)[90. API Gateway DevSecOps: Policy as Code, Testing, and Runtime Feedback](https://api7.ai/learning-center/api-gateway-guide/api-gateway-devsecops) 10 Platform Engineering and Planning [View this topic · 10](https://api7.ai/learning-center/api-gateway-guide?topic=platform-governance)[91. API Discovery and Documentation at the Gateway: Inventory, Ownership, and Drift](https://api7.ai/learning-center/api-gateway-guide/api-discovery-documentation-gateway)[92. WebAssembly Plugins for API Gateways: Portability, Isolation, and APISIX Boundaries](https://api7.ai/learning-center/api-gateway-guide/api-gateway-webassembly-plugins)[93. Monitoring API Gateways with Prometheus and Grafana: Metrics, Dashboards, and Alerts](https://api7.ai/learning-center/api-gateway-guide/monitor-api-gateways-prometheus-grafana)[94. API Gateway Reliability Engineering: SLOs, Failure Isolation, and Incident Response](https://api7.ai/learning-center/api-gateway-guide/api-gateway-reliability-engineering)[95. API Gateways for Edge AI Inference: Routing, Constraints, and Observability](https://api7.ai/learning-center/api-gateway-guide/api-gateways-edge-ai-inference)[96. Reducing Cloud Cost with API Gateway Controls: Measurement Before Optimization](https://api7.ai/learning-center/api-gateway-guide/reducing-cloud-cost-api-gateway-controls)[97. Improving API Developer Experience with Gateway Standards and Self-Service](https://api7.ai/learning-center/api-gateway-guide/improving-api-developer-experience-gateway-self-service)[98. API Gateway Change Management: Compatibility, Progressive Delivery, and Rollback](https://api7.ai/learning-center/api-gateway-guide/api-gateway-change-management-rollback)[99. Operating Serverless APIs: Cold Starts, Idempotency, and Asynchronous Handoffs](https://api7.ai/learning-center/api-gateway-guide/operating-serverless-apis-gateway)[100. Planning an API Gateway Roadmap for the Next Five Years](https://api7.ai/learning-center/api-gateway-guide/planning-api-gateway-roadmap-next-five-years) [API Gateway Guide](https://api7.ai/learning-center/api-gateway-guide)[Platform Engineering and Planning](https://api7.ai/learning-center/api-gateway-guide?topic=platform-governance) On this page On this page - [Key Takeaways](#key-takeaways) - [Define What “Discovered” Means](#define-what-discovered-means) - [Reconcile Four Views](#reconcile-four-views) - [Build the Inventory Record](#build-the-inventory-record) - [Use OpenAPI as the Reference Contract](#use-openapi-as-the-reference-contract) - [Collect Gateway Evidence Safely](#collect-gateway-evidence-safely) - [Classify Drift Before Fixing It](#classify-drift-before-fixing-it) - [Publish for the Intended Audience](#publish-for-the-intended-audience) - [Retire an API as a Multi-System Change](#retire-an-api-as-a-multi-system-change) - [Discovery and Documentation Checklist](#discovery-and-documentation-checklist) - [FAQ](#faq) - [Can the gateway generate complete API documentation?](#can-the-gateway-generate-complete-api-documentation) - [Is traffic discovery safe to publish automatically?](#is-traffic-discovery-safe-to-publish-automatically) - [Should the gateway export become the source of truth?](#should-the-gateway-export-become-the-source-of-truth) - [Next Steps](#next-steps) Article 91 # API Discovery and Documentation at the Gateway: Inventory, Ownership, and Drift API7.ai September 22, 2026 An API gateway is a valuable source of discovery evidence because it knows which hosts, paths, methods, policies, and upstreams it is configured to handle. It is not a complete API inventory and cannot generate trustworthy documentation from traffic or routes alone. A dependable program reconciles four views: the reviewed API contract, the effective gateway state, observed exposure and traffic, and an ownership catalog. Documentation is then published from approved contracts and guides, while differences become owned drift work rather than silent source changes. ## Key Takeaways - Treat gateway configuration and traffic as observed evidence, not the sole source of truth. - Give every API an owner, audience, environment, version, data class, lifecycle state, and retirement plan. - Publish reference documentation from a reviewed OpenAPI description plus human-authored guidance. - Reconcile missing, unexpected, duplicated, stale, and unreachable APIs across sources. - Keep public, partner, internal, and administrative catalogs separate by policy. - Verify retirement at the gateway, DNS, upstream, portal, client, and data layers. ## Define What “Discovered” Means Different sources answer different questions: | Source | What it can show | What it cannot prove alone | | --------------------------------------- | --------------------------------------------------------- | ------------------------------------------------------------- | | OpenAPI repository | Intended operations, schemas, security contract, version | That the contract is deployed or accurate | | Gateway configuration | Effective route, plugin, upstream, and exposure settings | Undocumented internal calls or application behavior | | Traffic observation | Hosts, paths, methods, status, volume, and active clients | Legitimate ownership, complete schemas, or safe authorization | | Service catalog | Owner, system, environment, data class, lifecycle | That every endpoint is reachable only as recorded | | Developer portal | What approved consumers can find and read | Hidden, shadow, retired, or direct-backend exposure | | DNS, load balancer, and cloud inventory | Externally or internally addressable surfaces | API semantics and policy correctness | Discovery should create a candidate or discrepancy, not automatically publish an API. Observed traffic can include scanners, typo paths, private data, and deprecated clients. ## Reconcile Four Views ``` flowchart LR C[Reviewed OpenAPI and guides] --> R[Reconciliation service] G[Effective gateway inventory] --> R T[Observed hosts paths methods and clients] --> R O[Ownership and lifecycle catalog] --> R R --> D[Drift queue with owner and severity] R --> P[Approved documentation release] P --> X[Public partner or internal portal] D -->|reviewed correction| C D -->|reviewed gateway change| G ``` The reconciliation service compares evidence. It does not copy runtime state into source or publish observed traffic automatically. Each correction follows the owner of the defective artifact. ## Build the Inventory Record Use stable identifiers rather than only display names. A useful record includes: - API and operation ID; - owning team and on-call destination; - business purpose and supported consumers; - public, partner, internal, or administrative audience; - environment, region, hostname, base path, and protocol; - contract version and gateway configuration revision; - authentication, coarse authorization, and sensitive-data classification; - upstream service and bypass controls; - lifecycle state: proposed, active, deprecated, retired, or exception; - deprecation date, replacement, last observed use, and retirement owner; - documentation URL and last verification result. OWASP API Security Top 10 2023 identifies [Improper Inventory Management](https://api-security.owasp.org/editions/2023/en/0xa9-improper-inventory-management/) as a risk involving unclear hosts, environments, versions, documentation, and retirement. Inventory is therefore an operational security control, not just a portal index. ## Use OpenAPI as the Reference Contract [OpenAPI 3.1.2](https://spec.openapis.org/oas/v3.1.2.html) defines a language-agnostic description that lets humans and computers understand an HTTP API surface. An OpenAPI Description can feed reference documentation, validation, tests, and client tooling. It still needs review. Verify paths, methods, parameters, schemas, responses, servers, security requirements, examples, and external references against the deployed behavior. OpenAPI also warns that external resources may be untrusted, reference cycles can exhaust tools, and Markdown or HTML fields require sanitization. The Operation Object's `deprecated` Boolean defaults to `false`. With `true`, consumers are told to avoid the operation; with `false` or omission, the document does not promise indefinite support. Neither branch disables the route at the gateway. Retirement needs a separate traffic and lifecycle action. Reference documentation is only one layer. Add task-oriented quick starts, authentication setup, error handling, limits, examples, changelogs, migration guidance, support, and status information. The companion guide [Using OpenAPI for API Documentation](https://api7.ai/learning-center/api-101/using-openapi-for-api-documentation) covers the contract-authoring workflow. ## Collect Gateway Evidence Safely For Apache APISIX 3.19.0, the [Admin API](https://apisix.apache.org/docs/apisix/3.19/admin-api/) exposes Route, Service, Upstream, Consumer, certificate, and other configuration resources. Read access to that API is still privileged: configuration can reveal internal hosts, plugin settings, identity structure, and secret references. Use a restricted operator network and managed credential. Export only the fields needed for inventory, redact secrets, tag the source cluster and revision, and preserve collection time. A successful read says what the selected control plane returned; it does not prove every data plane applied the same revision or that direct upstream exposure is absent. Normalize route evidence into stable fields such as: ``` { "gateway_cluster": "prod-eu-a", "route_id": "orders-v2-get", "hosts": ["api.example.com"], "methods": ["GET"], "paths": ["/v2/orders/*"], "service_id": "orders-v2", "observed_config_revision": "sha256:example", "collected_at": "2026-09-22T00:00:00Z" } ``` This is an inventory shape, not an APISIX Admin API response schema. The digest is a placeholder and must come from the operator's actual release evidence. ## Classify Drift Before Fixing It | Difference | Likely owner | Safe next action | | --------------------------------------- | -------------------------- | -------------------------------------------------------------------- | | Contract operation missing from gateway | Delivery or rollout owner | Confirm environment and release intent before creating a route | | Gateway route missing from contract | API and platform owners | Determine whether it is internal, emergency, stale, or shadow | | Traffic on a deprecated version | Product and client owners | Identify allowed clients and execute migration plan | | Portal page points to old contract | Documentation owner | Rebuild from the approved version and verify links/examples | | DNS or load balancer bypasses gateway | Network and service owners | Close or explicitly govern the alternate path | | Owner missing or unreachable | Platform governance | Escalate, restrict exposure if risk requires, and assign stewardship | Do not automatically delete an unexpected route. It may be an authorized incident workaround. Record actor, purpose, expiry, and follow-up, then reconcile through review. ## Publish for the Intended Audience Separate catalog visibility from runtime authorization. Hiding a portal page does not secure a route, and publishing documentation does not grant access. In API7 Enterprise 3.10.x, [API Products](https://docs.api7.ai/api7-gateway/developer-portal/key-concepts/api-products) can package gateway Services for the Developer Portal and generate documentation from attached OpenAPI specifications. The documentation distinguishes gateway products from external products; external products are not proxied by API7 Gateway and do not support the same subscription or credential path. Treat this as a product-specific publication option, not an Apache APISIX open-source capability. Before publication, verify: - the product contains only intended Services, hosts, and versions; - visibility matches public or authenticated audience policy; - authentication instructions match the deployed gateway; - examples use non-production placeholders and succeed in the intended sandbox; - limits, error responses, and deprecation notices are current; - internal names, secret references, and sensitive schemas are absent; - the portal release is tied to an approved contract revision. ## Retire an API as a Multi-System Change Deprecation communicates intent; retirement removes supported use. A controlled retirement should: 1. identify clients and owners without treating a correlation field as trusted identity; 2. publish replacement and deadline; 3. prevent new subscriptions or credentials where applicable; 4. monitor allowed legacy use and contact owners; 5. remove or deny gateway routes at the approved time; 6. close direct DNS, load-balancer, and upstream exposure; 7. remove portal pages or mark archived evidence; 8. verify that old traffic fails as designed and retained data follows policy. Keep audit evidence for the decision and final checks. A route returning no recent traffic is not proof that no client depends on it; observation windows, seasonal use, and missing telemetry matter. ## Discovery and Documentation Checklist - Does every active API have an accountable owner and support path? - Are contract, gateway, traffic, and catalog revisions recorded separately? - Can the inventory distinguish public, partner, internal, and administrative exposure? - Are external OpenAPI references pinned, bounded, and sanitized? - Are observed paths treated as candidates rather than automatically documented APIs? - Is privileged gateway configuration redacted and access controlled? - Does each drift item identify the defective artifact and its owner? - Do portal visibility and gateway authorization remain separate controls? - Does deprecation include client evidence, replacement, deadline, and retirement action? - Has bypass exposure been checked after a route is removed? ## FAQ ### Can the gateway generate complete API documentation? No. It can provide route and policy evidence, but it usually lacks complete schemas, domain semantics, examples, error meaning, and user tasks. ### Is traffic discovery safe to publish automatically? No. Traffic may contain unowned, hostile, mistyped, private, or deprecated paths. Triage and map it to an approved contract and owner first. ### Should the gateway export become the source of truth? Usually no. Keep the reviewed contract and policy as desired state; use the gateway export as observed state for reconciliation. ## Next Steps Connect the inventory to [OpenAPI-driven gateway operations](https://api7.ai/learning-center/api-gateway-guide/openapi-driven-api-gateway-operations), [API documentation authoring](https://api7.ai/learning-center/api-101/using-openapi-for-api-documentation), and [governed API delivery](https://api7.ai/learning-center/api-gateway-guide/api-gateway-modernization). [Previous topic · Advanced Gateway Applications**API Gateway DevSecOps: Policy as Code, Testing, and Runtime Feedback**](https://api7.ai/learning-center/api-gateway-guide/api-gateway-devsecops)[Next article**WebAssembly Plugins for API Gateways: Portability, Isolation, and APISIX Boundaries**](https://api7.ai/learning-center/api-gateway-guide/api-gateway-webassembly-plugins) On this page - [Key Takeaways](#key-takeaways) - [Define What “Discovered” Means](#define-what-discovered-means) - [Reconcile Four Views](#reconcile-four-views) - [Build the Inventory Record](#build-the-inventory-record) - [Use OpenAPI as the Reference Contract](#use-openapi-as-the-reference-contract) - [Collect Gateway Evidence Safely](#collect-gateway-evidence-safely) - [Classify Drift Before Fixing It](#classify-drift-before-fixing-it) - [Publish for the Intended Audience](#publish-for-the-intended-audience) - [Retire an API as a Multi-System Change](#retire-an-api-as-a-multi-system-change) - [Discovery and Documentation Checklist](#discovery-and-documentation-checklist) - [FAQ](#faq) - [Can the gateway generate complete API documentation?](#can-the-gateway-generate-complete-api-documentation) - [Is traffic discovery safe to publish automatically?](#is-traffic-discovery-safe-to-publish-automatically) - [Should the gateway export become the source of truth?](#should-the-gateway-export-become-the-source-of-truth) - [Next Steps](#next-steps)