What is OpenAPI / Swagger, and why is it useful?
Quick Answer
OpenAPI is a machine-readable specification that describes an HTTP API — its endpoints, parameters, request/response schemas and auth. Swagger is the tooling around it: interactive docs (Swagger UI), the spec generator (Swashbuckle / the built-in Microsoft.AspNetCore.OpenApi), and client-code generators.
OpenAPI is a standard format for describing an API — every endpoint, what it accepts, what it returns, the auth scheme — in a JSON or YAML document. Swagger is the ecosystem around it: Swagger UI gives you an interactive page to try the endpoints, and generators produce the spec from your code and typed client libraries from the spec. So instead of a consumer reading prose docs and writing HTTP calls by hand, they generate a strongly typed client. In ASP.NET Core the framework builds the document from your controllers and DTOs.
- ASP.NET Core generates the spec from your controllers, DTOs and attributes —
[ProducesResponseType], XML comments and[Produces]improve it. - Consumers get generated typed clients (NSwag, openapi-generator) instead of hand-writing HTTP calls.
- Contract-first workflows write the OpenAPI doc first and generate server stubs.
- Since .NET 9 the built-in generator replaces Swashbuckle for producing the document; you still choose a UI (Swagger UI, Scalar, Redoc).