> For the complete documentation index, see [llms.txt](https://docs.umbraco.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.umbraco.com/umbraco-cms/extend-your-project/tutorials/creating-a-backoffice-api/adding-a-custom-openapi-document.md).

# Adding a Custom OpenAPI Document

By default, all controllers based on `ManagementApiControllerBase` are included in the default Management API OpenAPI document. To put them in a dedicated document instead, register an OpenAPI document with `AddBackOfficeOpenApiDocument` and tag your controllers with `[MapToApi]`.

Register the document in a composer:

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

```csharp
using Umbraco.Cms.Api.Common.OpenApi;
using Umbraco.Cms.Api.Management.OpenApi;
using Umbraco.Cms.Core.Composing;

namespace My.Custom.ItemApi;

public class MyItemApiComposer : IComposer
{
    public void Compose(IUmbracoBuilder builder)
        => builder.AddBackOfficeOpenApiDocument(
            "my-item-api",
            document => document
                .WithTitle("My item API")
                .WithBackOfficeAuthentication());
}
```

{% endcode %}

`AddBackOfficeOpenApiDocument` applies Umbraco's defaults to the document. It includes any controller tagged with `[MapToApi("my-item-api")]`, applies the schema and operation ID conventions, and adds the document to the Swagger UI dropdown. `WithBackOfficeAuthentication()` wires up backoffice authentication.

See [API versioning and OpenAPI](/umbraco-cms/extend-your-project/server-side-extensions/api-versioning-and-openapi.md) for the underlying `AddOpenApi` primitive and other configuration options.

Tag your controller with `[MapToApi]` to route it into the document. Because `ManagementApiControllerBase` already carries `[MapToApi("management")]`, the attribute on your controller overrides that and moves the endpoint out of the default Management document.

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

```csharp
using Umbraco.Cms.Api.Common.Attributes;
using Umbraco.Cms.Api.Management.Controllers;

namespace My.Custom.ItemApi;

[MapToApi("my-item-api")]
public class MyItemApiController : ManagementApiControllerBase
{
    // your endpoints here
}
```

{% endcode %}

When you visit the Swagger UI, "My item API" has its own OpenAPI 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, enable **Disable cache** in the **Network** tab of your browser's developer tools.
{% endhint %}


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## 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, and the optional `goal` query parameter:

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

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

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.