Documentation with Swagger/OpenAPI and Scalar: Make Your API Self-Describing

We've completed the security block; your API is now solid and protected. But there's a problem: no one besides you knows how to use it. Which endpoints exist, what data do they expect, what do they return? You don't want to have to explain the answers to these questions by hand every time. So today we make your API self-describing: with OpenAPI, Swagger, and a modern alternative, Scalar.

Why Is Documentation So Important?

You wrote an API, but the ones who'll use it are others: your frontend developer, your mobile team, maybe developers at another company. They don't have access to the knowledge in your head. They need to learn from somewhere which data to send to which address and what they'll get in return. The bad option is explaining this by message, email, or word every time; both tiring and error-prone.

A good API carries its own guide with it. Just like the user manual that comes out of a device's box: when the user picks up the product, they don't have to ask anyone to know what to do. API documentation does this too; it explains how to use the API, without you being there, in a clear and up-to-date way.

OpenAPI: A Common Language

OpenAPI is a standard format that describes how an API works. It pours all the endpoints in your API, the data they expect, and the response they return into a structured document that machines can also read. This document is usually a JSON file and is like a complete map of the API.

The power of OpenAPI comes from it being a standard. There are dozens of tools built on this format: documentation interfaces, testing tools, even tools that automatically generate client code for your API. Once you produce the OpenAPI document, this whole ecosystem becomes able to talk to your API. Note: "OpenAPI" and "Swagger" are sometimes confused; in short, OpenAPI is a standard, while Swagger is the family of tools that grew around this standard.

OpenAPI Support in .NET 9

Good news: .NET 9 supports producing an OpenAPI document out of the box. Do you remember those AddOpenApi and MapOpenApi lines we saw while setting up the project in the second article? Well, they were doing exactly this job, but we hadn't dwelt on it. In Program.cs, these two pieces are enough:

builder.Services.AddOpenApi();

This line registers the service that will produce the OpenAPI document. Then, on the app side, you publish the document through an address:

if (app.Environment.IsDevelopment())
{
    app.MapOpenApi();
}

This condition is important: you usually keep the OpenAPI document open only in the development environment, because, as we touched on while discussing environment layers in the fifteenth article, you may not want to expose the internal structure of the API to everyone in production. When you run the application and go to /openapi/v1.json, you see the JSON document containing the entire map of the API. This document is produced automatically from your code, not by hand; when you add an endpoint, the document updates itself too.

Raw JSON Isn't Enough: A Human-Visible Interface

The OpenAPI document is great for machines, but a human can't comfortably explore the API by looking at that raw JSON. This is where documentation interfaces come in. They take the OpenAPI document and turn it into a beautiful, browsable, and even interactive page. The best known is Swagger UI.

Swagger UI shows all the API's endpoints as a list; you can click each one and see which parameters it takes and what it returns. Moreover, you can make requests to the endpoints directly from that page; you can try the API in the browser without needing a separate testing tool. This interactivity turns documentation from dead text into a living playground.

Scalar: A Modern Alternative

Swagger UI has been the standard for many years, but recently a more modern alternative is standing out: Scalar. Scalar also uses the same OpenAPI document but offers a cleaner, faster, and more visually pleasing interface. This is the reason it's quickly becoming popular in the .NET community: it does the same job but the experience is more enjoyable.

Adding Scalar is quite simple. First you add the package to your project:

dotnet add package Scalar.AspNetCore

Then, on the app side, you add Scalar right next to the line that publishes the OpenAPI document:

if (app.Environment.IsDevelopment())
{
    app.MapOpenApi();
    app.MapScalarApiReference();
}

When you run the application and go to /scalar/v1, you see all the API's endpoints in a modern interface. Notice: Scalar doesn't produce something from scratch; it takes your already-existing OpenAPI document and gives it a beautiful face. So if the OpenAPI foundation is ready, moving to Scalar is a one-line job.

Enriching the Documentation

Automatically produced documentation is a good start, but you can make it even more useful. You can enrich it with descriptions of what your endpoints do and what their parameters mean. Also, specifying which status codes an endpoint can return seriously eases the work of whoever uses the documentation:

[HttpGet("{id}")]
[ProducesResponseType(StatusCodes.Status200OK)]
[ProducesResponseType(StatusCodes.Status404NotFound)]
public async Task GetById(int id)
{
    var user = await _userService.GetByIdAsync(id);
    if (user is null)
    {
        return NotFound();
    }
    return Ok(user);
}

The [ProducesResponseType] attributes here inform the documentation that this endpoint can return 200 or 404. So someone using your API sees which responses they can expect before even writing code. What we learned while discussing status codes in the fifth article reflects into the documentation here; returning the right status code is valuable not only for the operation but also for the clarity of the documentation.

A Small Experiment

First add AddOpenApi and MapOpenApi to your project (make sure, if they're already in the template) and go to /openapi/v1.json to see the raw OpenAPI document; notice that the API's map is produced automatically. Then install the Scalar package, open the /scalar/v1 address, and browse your endpoints in the modern interface. Make a request to an endpoint directly from this interface and see the response there. If you like, add a few [ProducesResponseType] and observe how the documentation is enriched. This experiment shows how much value documentation produces with how little effort.

In the next article we move on to testing. The first step will be unit testing: we'll talk about how to test the individual pieces of your code in isolation, with xUnit and Moq. Your API is now both secure and well-documented; next is the way to be sure that it works correctly.