Support Center & Knowledge base

Swagger

Swagger is a great tool for interacting with APIs on a webserver without the need for a custom UI. To enable the use of Swagger with a Dolittle AspNetCore Bounded Context, we expose special APIs and generate OpenAPI documents based on Commands, Queries and Events in your bounded context. This allows for quicker development of the business logic and simplifies working on the domain and readmodels separately. Please note however that these APIs are only ment as a development tool and not for production use.

Enabling Swagger Debugging

First, install the Dolittle.AspNetCore.Debugging.Swagger NuGet package. For example by putting the following PackageReference in your Core.csproj file.

<PackageReference Include="Dolittle.AspNetCore.Debugging.Swagger" Version="1.*" />

Next, add the required services in your Startup.cs file.

public void ConfigureServices(IServiceCollection services)
{
    services.AddDolittleSwagger();
}

Lastly, enable the generated endpoints and the Swagger UI in your Startup.cs file.

public void Configure(IApplicationBuilder app, IHostingEnvironment env)
{
    if (env.IsDevelopment())
    {
        app.UseDolittleSwagger();
    }
}

Using the Swagger UI to interact with your Bounded Context

After starting the AspNetCore server with e.g. dotnet run in the /Core directory, the server will output its base URL - http://localhost:5000 for this example.

Hosting environment: Development
Content root path: /Application/BoundedContext/Core
Now listening on: http://localhost:5000

Navigate to /swagger - http://localhost:5000/swagger for this example - in your favorite browser to access the Swagger UI. The page should look something like this:

In the top-right corner, you can select whether you would like to execute commands, queries or inject events. The lower part of the page will list out all artifacts of your application grouped by features. Clicking on one of the artifacts will show its structure, and subsequently clicking on Try it out will allow you to enter values for the artifact.

Finally, clicking on Execute will execute the command, query or inject the event, and show the results in a new panel. Below is an example of the result from a query execution.

Notes about TenantId

All applications created using the Dolittle framework are multi-tenant by default. This means that everything happens in the context of a tenant, defined by its tenantId. Usually this is handled without you having to think too much about it, but to allow simple experimentation with data from multiple tenants, the TenantId parameter is added to all endpoints in the SwaggerUI. By default this is set to the globally defined Development Tenant, but you are free to set this to any GUID of your choosing. Just ensure that the TenantId is defined in the .dolittle/tenants.json configuration file in your bounded context Core project.

Notes about Event injection

In production, Commands are the only way to change the state of your Bounded Context. This tool however allow you to inject events directly into the Event Store to decouple development of Commands and Domain from ReadModels and Queries. Be aware that this mechanism bypasses any validation that you might have in your Domain, so it might lead to a corrupt state of your application, and it is probably a good idea to start with a fresh event store when going back to domain development.

The debugging UI will also list events you have imported from other Bounded Contexts, so it is possible to debug multi bounded context applications without the need to run all of them at the same time and use the Event Horizon to transport events between them.

The EventSourceId parameter in the UI corresponds to the Id of the Aggregate Root that emitted the event.