REST API Bindings: Building own API

This feature is new in DotVVM 2.0. See REST API Bindings for more details about configuration.

If you decide to build the REST API using ASP.NET Web API or ASP.NET MVC Core, there are NuGet packages you can use to allow sharing objects between DotVVM application and the REST API.

These NuGet packages work with Swashbuckle, a popular library that exposes Swagger JSON metadata.

Installing Swashbuckle extensions for DotVVM (OWIN)

First, make sure you have Swashbuckle installed and configured in your project.

Swashbuckle - classic ASP.NET

Then, install the following NuGet package to the REST API project:

Install-Package DotVVM.Api.Swashbuckle.Owin

Installing Swashbuckle extensions for DotVVM (ASP.NET Core)

First, make sure you have Swashbuckle installed and configured in your project.

Swashbuckle - ASP.NET Core
Swashbuckle - ASP.NET Core - Newtonsoft (This package is necessary only for DotVVM 2.5+ projects that target ASP.NET Core 2.x, or that are using Newtonsoft.Json serializer with ASP.NET Core 3.x)

Then install the following NuGet package to the REST API project:

Install-Package DotVVM.Api.Swashbuckle.AspNetCore

Configure Swashbuckle extensions for DotVVM (OWIN)

To enable DotVVM integration, call the EnableDotvvmIntegration extension method in the Swashbuckle configuration.

In OWIN, this is typically done in SwaggerConfig.cs file.

config.EnableSwagger(c =>
    {
        ...
        c.EnableDotvvmIntegration(opt => 
        {
            // TODO: configure DotVVM Swashbuckle options    
        });
    })
    .EnableSwaggerUi(c => { ... });

Configure Swashbuckle extensions for DotVVM (ASP.NET Core)

To enable DotVVM integration, call the EnableDotvvmIntegration extension method in the Swashbuckle configuration.

In ASP.NET Core, this is configured in Startup.cs file.

services.Configure<DotvvmApiOptions>(opt => 
{
    // TODO: configure DotVVM Swashbuckle options
});

services.AddSwaggerGen(options => {
    ...
    options.EnableDotvvmIntegration();
});

Additionally, in case of DotVVM 2.5 or newer with ASP.NET Core 2.x or ASP.NET Core 3.x with Newtonsoft.Json serializer, you also need to call AddSwaggerGenNewtonsoftSupport.

services.AddSwaggerGenNewtonsoftSupport();

Registering known types

By default, DotVVM Command Line generates classes for all types used in the REST API (in both C# and TypeScript clients). For example, if the API returns a list of orders, there will be the Order class in the generated client.

If the API is hosted in the same project as the DotVVM application, or if the API project can share these types with the DotVVM application using a class library, you can register these types as known types. In this case, they won't be included in the generated client and you need to make sure both DotVVM and API can see these types with the same name and namespace.

To register known types, configure the DotVVM integration like this:

// OWIN
c.EnableDotvvmIntegration(opt => 
{
    // add a single type
    opt.AddKnownType(typeof(Order));

    // add all types from the assembly
    opt.AddKnownAssembly(typeof(Order).Assembly);

    // add all types from the namespace
    opt.AddKnownNamespace(typeof(Order).Namespace);
});

// ASP.NET Core
services.Configure<DotvvmApiOptions>(opt => 
{
    // add a single type
    opt.AddKnownType(typeof(Order));

    // add all types from the assembly
    opt.AddKnownAssembly(typeof(Order).Assembly);

    // add all types from the namespace
    opt.AddKnownNamespace(typeof(Order).Namespace);
});

Edit on Github