OpenAPI in .NET Core

by

Introduction

Correct API documentation is essential.

Documentation can be generated from an OpenAPI specification.

An OpenAPI specification describes the capabilities of our API, and how to interact with it.

It’s standardized, and in JSON or YAML format.

What is Swagger

OpenAPI specifications and Swagger specifications are the same thing.

Swagger is a set of Open Source tools built around OpenAPI.

Swashbuckle.AspNetCore helps working with OpenAPI in .NET Core.

Swashbuckle.AspNetCore

  • Generates an OpenAPI specification from your API.
  • Wraps Swagger-UI and provides an embedded version of it.
  • NSwag is an alternative for Swashbuckle.

Swashbuckle is used both for OpenAPI generation and for generating a documentation UI.

OpenAPI in .NET Core Web API (New Project)

When creating new Project, we can simple click a check box to enable OpenAPI support in our project.

I simply start by creating a new Web API project in Visual Studio and checked Enable OpenAPI support as follows:

This result in following code in Program.cs:

Also, Swashbuckle.AspNetCore package is installed as follows:

Running the Application

Now, lets run the application and it will show us a Nice UI as below

We can see that we have a documentation UI which is showing the application controller endpoint and schemas information as well.

Further expanding shows more details about the endpoint, input parameters and response information.

We can also test our API from here by clicking Try it Out button shown above. Following is the result of the API call:

Just by clicking a checkbox, this all will be setup for a new .NET web API project.

On UI, we can click the specification link , will route us to the swagger.json file.

This is the OpenAPI specification that was generated by Swashbuckle:

Use cases for OpenAPI

We already saw API documentation UI which is generated from the specification. Following are the typical use cases of Open API specifications:

  • Generating a documentation UI.
  • The UI can also be used to test the API.
  • Generating Client classes (DTOs, or even full client).
  • Helping with generating tests for an API.

Following picture shows these usages:

Adding and Configuring OpenAPI in Existing Applications

A more realistic scenario is that we might have an existing API and would like to enable OpenAPI support for it.

Let’s see how to do this.

I have an existing .NET core web API application. If you are following along, you may already know this application from other posts.

Following is the solution structure

This project is using Startup.cs file for configuration purposes.

First step, lets add NuGet package as shown below:

Next, lets configure the middle-ware by updating Startup.cs file as shown below

with these changes in place, we can now run the project and navigate to /swagger endpoint

here, we can see the documentation UI and link to the swagger.json specification.

That was easy and by simply adding a NuGet package and configuring middleware, we now have OpenAPI specification enabled for our web API. We also have a nice User interface which we can use to learn more about the API and test it as well.

Summary

In this post, we learned that the correct documentation of an API is very important. Documentation can be generated from an OpenAPI specification. An OpenAPI specification describes the capabilities of our API, and how to interact with it.

We learned that Swagger specification and Open-API specifications are the same thing. Swagger is a set of Open Source tools built around OpenAPI. Swashbuckle.AspNetCore helps working with OpenAPI in .NET Core.

We then saw demos of how to add OpenAPI in a new and existing .NET Core web API project.

You can also check the published web api on AWS lambda on this URL.

Let me know if you have some questions or comments. Till next time, Happy Coding!