وثائق API مكشوفة

API documentation is meant to be read. The question is by whom. OpenAPI / Swagger specs are extraordinarily useful in development — they generate clients, drive contract testing, and document the API for new team members — but those same properties make them a recon goldmine when shipped to production. The full structure of every endpoint, every parameter name and type, every authentication scheme, every error response shape, served as a single JSON document at a predictable URL. Frameworks like FastAPI, NestJS, Express with swagger-jsdoc, and Spring Boot Actuator publish these by default; many teams never explicitly turned them off when shipping to prod.

FastAPI ships `/docs`, `/redoc`, and `/openapi.json` by default — fantastic for development, dangerous if those URLs reach production. NestJS via @nestjs/swagger does the same at `/api`. Spring Boot Actuator publishes `/actuator/openapi` when included. Express apps with `swagger-ui-express` typically mount at `/api-docs` or `/swagger`. Each one returns a structured document listing every route, the HTTP methods accepted, every query/path/body parameter with types and constraints, the authentication scheme, and (in detailed configs) example payloads and response shapes. The attacker doesn't have to fuzz; they have the contract.

Reduces the attacker's effort dramatically. Instead of fuzzing for endpoints (slow, noisy, partial coverage), they have the complete list with parameter names and types. This makes targeted attacks against authorization gaps (IDOR, mass assignment), input validation flaws (SQL/NoSQL injection), and rate-limit bypasses much more efficient. For B2B SaaS, exposed docs also leak product surface — knowing which `admin.*` endpoints exist may inform competitive intelligence as much as attack planning.

Gate API documentation behind authentication, or remove it from production entirely. The cleanest pattern: serve docs only in development environments via env-driven config. FastAPI: `app = FastAPI(docs_url=None, redoc_url=None, openapi_url=None)` in production. NestJS: only call `SwaggerModule.setup` when `process.env.NODE_ENV !== 'production'`. Spring Boot: exclude springfox/springdoc dependencies from prod builds, or set `springdoc.api-docs.enabled=false`. If documentation is needed for partners or developers, host it on a separate authenticated subdomain that doesn't expose the live API. As a defense-in-depth layer, configure your edge (CDN, WAF) to block requests to the standard documentation paths in production.