# Adding a Custom Swagger Document

By default, all controllers based on ManagementApiControllerBase will be included in the default Management API Swagger document.

When building custom Management API controllers, sometimes it's preferable to have a dedicated Swagger document for them. Doing so is a three-step process:

1. Register the Swagger document with Swagger UI.
2. Instruct Swagger UI to utilize Umbraco authentication for the Swagger document.
3. Move the controllers to the Swagger document.

The following code exemplifies how to achieve the first two steps;

{% code title="MyItemApiComposer.cs" %}

```csharp
using Microsoft.Extensions.Options;
using Microsoft.OpenApi.Models;
using Swashbuckle.AspNetCore.SwaggerGen;
using Umbraco.Cms.Api.Management.OpenApi;
using Umbraco.Cms.Core.Composing;

namespace UmbracoDocs.Samples;

public class MyItemApiComposer : IComposer
{
    public void Compose(IUmbracoBuilder builder)
    {
        builder.Services.ConfigureOptions<MyItemApiSwaggerGenOptions>();
    }
}

public class MyItemApiSwaggerGenOptions : IConfigureOptions<SwaggerGenOptions>
{
    public void Configure(SwaggerGenOptions options)
    {
        // register the custom Swagger document "my-item-api"
        options.SwaggerDoc(
            "my-item-api",
            new OpenApiInfo { Title = "My item API", Version = "1.0" }
        );

        // enable Umbraco authentication for the "my-item-api" Swagger document
        options.OperationFilter<MyItemApiOperationSecurityFilter>();
    }
}

public class MyItemApiOperationSecurityFilter : BackOfficeSecurityRequirementsOperationFilterBase
{
    protected override string ApiName => "my-item-api";
}
```

{% endcode %}

With this in place, the last step is to annotate the relevant API controllers with the MapToApi attribute:

{% code title="MyItemApiController.cs" %}

```csharp
[MapToApi("my-item-api")]
public class MyItemApiController : ManagementApiControllerBase
```

{% endcode %}

Now when we visit the Swagger UI, "My item API" has its own Swagger document:

![My item API in Swagger UI](/files/bDiuzTWnGIEcHo9BmOBO)

{% hint style="info" %}
Swagger UI sometimes has persistent caching, which can prevent the new definition from appearing immediately. If this happens, disable caching in the **Network** tab of your browser's developer tools.
{% endhint %}


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.umbraco.com/umbraco-cms/18.latest/extend-your-project/tutorials/creating-a-backoffice-api/adding-a-custom-swagger-document.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.