Documentation

An API without documentation is like a library with no card catalog or a complex machine with no instruction manual. It might be powerful and well-built, but if nobody knows how to use it, its value is lost. Good documentation is not an afterthought; it is a fundamental feature that turns your API from a simple service into a product that is a pleasure for other developers to use.

SliceFlow recognizes this and is designed from the ground up to make generating beautiful, interactive, and always-up-to-date documentation an almost effortless process.

The Problem with Manual Documentation

Traditionally, API documentation was written and maintained manually. This approach is fraught with problems:

• It’s tedious and time-consuming.
• It quickly becomes outdated as the code changes.
• It’s easy for the documentation and the actual API behavior to drift apart, leading to confusion and frustration for your users.

The SliceFlow Advantage: Documentation from Code

The secret to SliceFlow’s powerful documentation capabilities lies in its endpoint-centric design and the REPR pattern. Because every feature is broken down into a collection of small, focused classes, the framework already knows almost everything it needs to describe your API:

• The Endpoint class defines the route, HTTP verb, version, and security requirements.
• The Request class defines the exact shape and type of the input data.
• The Response class defines the exact shape and type of the output data.
• The Validator class defines the rules and constraints for the input.

This structure provides a rich, machine-readable blueprint of your entire API surface. All that’s missing is the human touch—the descriptions and examples that make the documentation truly useful.

The Summary: Adding the Human Element

This is the role of the Summary class. For each endpoint, you can create a corresponding summary class that provides the descriptive metadata needed to generate rich documentation.

internal sealed class AssignPermissionsSummary : Summary<AssignPermissions>
{
    public AssignPermissionsSummary()
    {
        Summary = "Assign Permissions";
        Description = "This endpoint assigns the given permission to the given user id.";
        ExampleRequest = new AssignPermissionRequest(Guid.CreateVersion7(), ["User.AssignPermissions"]);
    }
}

The framework automatically discovers this class (by the naming convention EndpointName + Summary) and uses it to enrich the API’s specification.

Bringing It to Life with OpenAPI and Scalar

SliceFlow uses this collection of metadata to automatically generate an OpenAPI specification (formerly known as Swagger). This is a standardized JSON file that describes every aspect of your API in a machine-readable format.

But a JSON file isn’t very user-friendly. To turn this specification into a beautiful, interactive experience, SliceFlow uses Scalar. Scalar takes the OpenAPI file and renders it as a polished, modern documentation website.

The Developer Experience

This entire system is configured for you out of the box. By default, when you run your SliceFlow application in a development environment, you can navigate to http://localhost:5076/scalar/v1 and you will be greeted with your fully interactive API documentation, powered by Scalar.

Here, developers consuming your API can:

• See a list of all available endpoints, neatly organized by tags.
• Click on any endpoint to see a detailed description, security requirements, and parameters.
• View example request bodies and the exact structure of success and error responses.
• Most importantly, use the interactive “Try It Out” feature to make live API calls directly from the documentation page.

Configuration: Simple and Secure

This entire documentation pipeline is configured with a few lines of code in Program.cs.

// In Program.cs
builder.ConfigureEndpointDocumentation();

// ...

app.UseEndpointDocumentation();

Crucially, the UseEndpointDocumentation() method is designed to be safe for production. It automatically checks the environment and will only expose the documentation UI when the application is running in Development. This prevents your internal API structure from being accidentally exposed to the public.

By building on a structure that is inherently self-describing and leveraging powerful open-source tools, SliceFlow transforms API documentation from a tedious chore into an automated, integrated, and valuable part of your development workflow.