The OpenAPI specification is a JSON-based, machine-readable interface description language for documenting, consuming, and visualizing RESTful web services. It defines a standardized, language-agnostic contract that lets humans and machines understand an API without reading its source code. section 3.2.1
OpenAPI addresses the maintenance cost of API documentation by generating descriptions automatically. In ASP.NET Core, Swashbuckle supplies services, middleware, and tools that produce an OpenAPI document and an interactive client. section 3.2 section 11.2.1
A useful OpenAPI description should make the API’s behavior and expectations easy to inspect:
- Describe endpoints, input parameters, and responses. section 11.5
- Provide request and response samples. section 11.5
- Group endpoints and emphasize authorization requirements. section 11.5
- Customize generated descriptions with data attributes and filter pipelines. section 11.5
ASP.NET Core API documentation
An ASP.NET Core web API can use Swashbuckle’s autodiscovery to generate an OpenAPI 3.0 description file named swagger.json. SwaggerUI then presents that description as an interactive, web-based client for testing endpoints. section 11.2.1
