OpenAPI is a language-agnostic specification for describing RESTful APIs. An OpenAPI document describes an application’s available URLs, how to call them, and the data types they return. That description lets tools display an API, test its endpoints, or generate a client without requiring the API’s source code. section 11.1 section 11.4.1
For an ASP.NET Core minimal API, a practical path is:
- Add Swashbuckle.AspNetCore, register endpoint exploration and Swagger generation, then enable the Swagger middleware. Swashbuckle uses endpoint metadata to generate and serve the document. section 11.1
- Open Swagger UI at /swagger to inspect endpoints, request and response schemas, and documented responses. Use Try it out to send a request. section 11.2
- Add endpoint metadata when the initial description is incomplete. For example, a GET endpoint that can return 404 may initially show only a 200 response; document the missing response rather than assuming the generated description is complete. section 11.2
Summaries and descriptions make the document more useful in Swagger UI and generated clients. In the setup shown here, WithSummary() and WithDescription() also require the Microsoft.AspNetCore.OpenApi package and WithOpenApi() for Swashbuckle to include them. WithOpenApi() can set parameter descriptions directly. Alternatively, Swashbuckle can read generated XML documentation comments from method-based endpoint handlers; in .NET 7, that approach does not support lambda or local-function handlers. section 11.5.1 section 11.5.3
.WithOpenApi(o =>
{
o.Parameters[0].Description = "The id of the fruit to fetch";
o.Summary = "Fetches a fruit";
return o;
});
This WithOpenApi() example sets both a parameter description and an endpoint summary. section 11.5.1
An OpenAPI document can also drive an optional strongly typed C# client. NSwag reads the saved JSON description and generates code for calling the described endpoints, including request serialization and response deserialization. The saved document is a snapshot: after changing the API description, refresh the JSON file and rebuild to regenerate the client. section 11.4 section 11.4.5
Treat the document as a useful description, not a promise that every API design or toolchain feature will fit. OpenAPI cannot fully describe some dynamic HATEOAS APIs, and tooling may lag newer specification features. Simple APIs and local testing are good reasons to try it; more complex requirements deserve evaluation before investing heavily in generation. section 11.6.1 section 11.6.3
