11 Documenting APIs with OpenAPI

In this chapter I introduce the OpenAPI specification for describing RESTful APIs, demonstrate how to use OpenAPI to describe a minimal API application, and discuss some of the reasons you might want to do so.

In section 11.1 you’ll learn about the OpenAPI specification itself and where it fits in to an ASP.NET Core application. You’ll learn about the libraries you can use to enable OpenAPI documentation generation in your app and how to expose the document using middleware.

Once you have an OpenAPI document, you’ll see how to do something useful with it in section 11.2, where we add Swagger UI to your app. Swagger UI uses your app’s OpenAPI document to generate a UI for testing and inspecting the endpoints in your app, which can be especially useful for local testing.

After seeing your app described in Swagger UI, it’s time to head back to the code in section 11.3. OpenAPI and Swagger UI need rich metadata about your endpoints to provide the best functionality, so we look at some of the basic metadata you can add to your endpoints.

11.1 Adding an OpenAPI description to your app

11.2 Testing your APIs with Swagger UI

11.3 Adding metadata to your minimal APIs

11.4 Generating strongly typed clients with NSwag

11.4.1 Generating a client using Visual Studio

11.4.2 Generating a client using the .NET Global tool

11.4.3 Using a generated client to call your API

11.4.4 Customizing the generated code

11.4.5 Refreshing the OpenAPI description

11.5 Adding descriptions and summaries to your endpoints

11.5.1 Using fluent methods to add descriptions

11.5.2 Using attributes to add metadata