The OpenAPI Document

Swashbuckle brings the power of the OpenAPI 3.0 Specification (formerly Swagger Specification) and related tools (Swagger UI, Swagger Codegen, ReDoc etc.) to ASP.NET Core with minimal developer effort.

It does this by inspecting your application code (routes, controllers, models, attributes etc.) to generate an “OpenAPI” document that describes your API. It then exposes that document as a JSON or YAML endpoint that can be consumed by various tools in the Swagger ecosystem, including the Swagger UI and Swagger Codegen client generator.

The following example illustrates the basic structure of an OpenAPI document generated by Swashbuckle:

The openapi keyword specifies the exact version of the Open Specification that the document is based on - currently v3.0.1.

The info section contains general information about your API. With the default setup, Swashbuckle will set the title to the name of your Startup DLL and the version to “1.0”. However, this data can be easily customized and enriched (e.g. adding a description, terms of service etc.) when configuring the Swagger generator. See Providing General API Info for more info.

The paths section defines the various routes exposed by your API, and the HTTP methods (“operations”) supported for those routes. An operation definition includes parameters (if any), a request body (if any), possible response status codes (such as 200 OK or 404 Not Found) and response contents.

The components section defines various definitions (e.g. schemas, security schemes etc.) that can be referenced elsewhere in the document. For example, The “CreateUser” operation shown above defines a requestBody that references the “User” schema definition rather than defining it inline.