OpenAPI (formerly Swagger) is the dominant standard for machine-readable HTTP API documentation. A single JSON or YAML file describes every endpoint the API exposes: paths, HTTP methods, query / body parameters, response shapes, status codes, security schemes. The spec drives both human-readable docs (Swagger UI, ReDoc, Stoplight) and code generation (server stubs, client SDKs, Postman collections, mock servers).
Conventions for spec location:
/openapi.jsonor/openapi.yaml(OpenAPI 3 default)/swagger.json(Swagger 2 / OpenAPI 2 default)/v3/api-docs(Springdoc default for Java)/api-docs(Express / Loopback default)
Public APIs typically publish their spec for SDK generation. Internal APIs sometimes ship the spec accidentally -- e.g., a misconfigured production deployment that left the dev / staging Swagger UI mounted. The exposed spec hands attackers a complete map of every endpoint and expected payload, dramatically lowering the cost of recon.
Whether to expose the spec is a deliberate choice tied to the API's audience: public-API operators want it indexed; internal-API operators want it gated behind authentication. There's no general "right answer" -- the security flag is "we found one; verify this matches your intent."