adding management api docs with some examples

14/umbraco-cms/extending-cms/custom-swagger-api.md

@@ -0,0 +1,218 @@
+---
+description: Example of a Custom API with Authorization and Swagger
+---
+
+# Custom API with Authorization and Swagger
+
+This article covers how to create a Custom API controller that is protected by the backoffice authorization policy. It also advertises itself in Swagger docs with authorization UI enabled.
+
+This example can be a starting point for creating a secure custom API in the Swagger documentation or using the API Controller. You can find other examples in the [API versioning and OpenAPI](../reference/api-versioning-and-openapi.md) article.
+
+{% hint style="info" %}
+
+Before following this guide familiarize yourself with the [Management API](../reference/management-api/README.md) article. There you can read more about the Swagger documentation and Authorization which will be used in this article.
+
+{% endhint %}
+
+1. In an Umbraco v14+ installation, create at the root of the project a new `.cs` file called `MyBackOfficeSecurityRequirementsOperationFilter`.
+
+2. Then add the following code so that the new API shows in the Swagger documentation and Swagger UI:
+
+{% code title="MyBackOfficeSecurityRequirementsOperationFilter.cs" lineNumbers="true" %}
+```csharp
+{
+using Asp.Versioning;
+using Microsoft.AspNetCore.Authorization;
+using Microsoft.AspNetCore.Mvc;
+using Microsoft.Extensions.Options;
+using Microsoft.OpenApi.Models;
+using Swashbuckle.AspNetCore.SwaggerGen;
+using Umbraco.Cms.Api.Common.Attributes;
+using Umbraco.Cms.Api.Common.Filters;
+using Umbraco.Cms.Api.Management.OpenApi;
+using Umbraco.Cms.Core;
+using Umbraco.Cms.Core.Composing;
+using Umbraco.Cms.Core.Models.Membership;
+using Umbraco.Cms.Core.Security;
+using Umbraco.Cms.Web.Common.Authorization;
+
+namespace Umbraco.Cms.Web.UI.New.Custom;
+
+//Necessary code for the new API to show in the Swagger documentation and Swagger UI
+public class MyBackOfficeSecurityRequirementsOperationFilter : BackOfficeSecurityRequirementsOperationFilterBase
+{
+    protected override string ApiName => "my-api-v1";
+}
+
+public class MyConfigureSwaggerGenOptions : IConfigureOptions<SwaggerGenOptions>
+{
+    public void Configure(SwaggerGenOptions options)
+    {
+        options.SwaggerDoc("my-api-v1", new OpenApiInfo { Title = "My API v1", Version = "1.0" });
+        options.OperationFilter<MyBackOfficeSecurityRequirementsOperationFilter>();
+    }
+}
+
+public class MyComposer : IComposer
+{
+    public void Compose(IUmbracoBuilder builder)
+        => builder.Services.ConfigureOptions<MyConfigureSwaggerGenOptions>();
+}
+
+//Creating the Controller
+[ApiController]
+[ApiVersion("1.0")] 
+[MapToApi("my-api-v1")] 
+[Authorize(Policy = AuthorizationPolicies.BackOfficeAccess)] 
+[JsonOptionsName(Constants.JsonOptionsNames.BackOffice)]
+[Route("api/v{version:apiVersion}/my")]
+public class MyApiController : Controller
+{
+    private readonly IBackOfficeSecurityAccessor _backOfficeSecurityAccessor;
+
+    public MyApiController(IBackOfficeSecurityAccessor backOfficeSecurityAccessor)
+        => _backOfficeSecurityAccessor = backOfficeSecurityAccessor;
+
+    [HttpGet("say-hello")]
+    [MapToApiVersion("1.0")]
+    [ProducesResponseType(typeof(string), StatusCodes.Status200OK)]
+    public IActionResult SayHello()
+    {
+        IUser currentUser = _backOfficeSecurityAccessor.BackOfficeSecurity?.CurrentUser
+                            ?? throw new InvalidOperationException("No backoffice user found");
+        return Ok($"Hello, {currentUser.Name}");
+    }
+}
+}
+```
+{% endcode %}
+
+- The `BackOfficeSecurityRequirementsOperationFilter` enables back-office authentication for Swagger UI.
+- `BackOfficeSecurityRequirementsOperationFilterBase` is an abstract base class that can be reused for custom APIs.
+
+2. Add the ApiController to setup the logic behind the endpoint:
+
+{% code title="MyBackOfficeSecurityRequirementsOperationFilter.cs" lineNumbers="true" %}
+```csharp
+{
+...
+
+//Creating the Controller
+[ApiController]
+[ApiVersion("1.0")] 
+[MapToApi("my-api-v1")] 
+[Authorize(Policy = "New" + AuthorizationPolicies.BackOfficeAccess)] 
+[JsonOptionsName(Constants.JsonOptionsNames.BackOffice)]
+[Route("api/v{version:apiVersion}/my")]
+public class MyApiController : Controller
+{
+    private readonly IBackOfficeSecurityAccessor _backOfficeSecurityAccessor;
+
+    public MyApiController(IBackOfficeSecurityAccessor backOfficeSecurityAccessor)
+        => _backOfficeSecurityAccessor = backOfficeSecurityAccessor;
+
+    [HttpGet("say-hello")]
+    [MapToApiVersion("1.0")]
+    [ProducesResponseType(typeof(string), StatusCodes.Status200OK)]
+    public IActionResult SayHello()
+    {
+        IUser currentUser = _backOfficeSecurityAccessor.BackOfficeSecurity?.CurrentUser
+                            ?? throw new InvalidOperationException("No backoffice user found");
+        return Ok($"Hello, {currentUser.Name}");
+    }
+}
+}
+```
+{% endcode %}
+
+<details>
+
+<summary>See the entire file: MyBackOfficeSecurityRequirementsOperationFilter.cs</summary>
+
+{% code title="MyBackOfficeSecurityRequirementsOperationFilter.cs" lineNumbers="true" %}
+```csharp
+using Asp.Versioning;
+using Microsoft.AspNetCore.Authorization;
+using Microsoft.AspNetCore.Mvc;
+using Microsoft.Extensions.Options;
+using Microsoft.OpenApi.Models;
+using Swashbuckle.AspNetCore.SwaggerGen;
+using Umbraco.Cms.Api.Common.Attributes;
+using Umbraco.Cms.Api.Common.Filters;
+using Umbraco.Cms.Api.Management.OpenApi;
+using Umbraco.Cms.Core;
+using Umbraco.Cms.Core.Composing;
+using Umbraco.Cms.Core.Models.Membership;
+using Umbraco.Cms.Core.Security;
+using Umbraco.Cms.Web.Common.Authorization;
+
+namespace Umbraco.Cms.Web.UI.New.Custom;
+
+//Necessary code for the new API to show in the Swagger documentation and Swagger UI
+public class MyBackOfficeSecurityRequirementsOperationFilter : BackOfficeSecurityRequirementsOperationFilterBase
+{
+    protected override string ApiName => "my-api-v1";
+}
+
+public class MyConfigureSwaggerGenOptions : IConfigureOptions<SwaggerGenOptions>
+{
+    public void Configure(SwaggerGenOptions options)
+    {
+        options.SwaggerDoc("my-api-v1", new OpenApiInfo { Title = "My API v1", Version = "1.0" });
+        options.OperationFilter<MyBackOfficeSecurityRequirementsOperationFilter>();
+    }
+}
+
+public class MyComposer : IComposer
+{
+    public void Compose(IUmbracoBuilder builder)
+        => builder.Services.ConfigureOptions<MyConfigureSwaggerGenOptions>();
+}
+
+//Creating the Controller
+[ApiController]
+[ApiVersion("1.0")] 
+[MapToApi("my-api-v1")] 
+[Authorize(Policy = AuthorizationPolicies.BackOfficeAccess)] 
+[JsonOptionsName(Constants.JsonOptionsNames.BackOffice)]
+[Route("api/v{version:apiVersion}/my")]
+public class MyApiController : Controller
+{
+    private readonly IBackOfficeSecurityAccessor _backOfficeSecurityAccessor;
+
+    public MyApiController(IBackOfficeSecurityAccessor backOfficeSecurityAccessor)
+        => _backOfficeSecurityAccessor = backOfficeSecurityAccessor;
+
+    [HttpGet("say-hello")]
+    [MapToApiVersion("1.0")]
+    [ProducesResponseType(typeof(string), StatusCodes.Status200OK)]
+    public IActionResult SayHello()
+    {
+        IUser currentUser = _backOfficeSecurityAccessor.BackOfficeSecurity?.CurrentUser
+                            ?? throw new InvalidOperationException("No backoffice user found");
+        return Ok($"Hello, {currentUser.Name}");
+    }
+}
+```
+{% endcode %}
+
+</details>
+
+3. Run the project and navigate to `{yourdomain}/umbraco/swagger`.
+4. From **Select a definition** choose the swagger documentation we have created with the above code, called **My API v1**.
+
+![Created Custom API in Swagger Documentation](./images/custom-api-swagger-example.png)
+
+Here we can find the endpoint that we have created:
+
+```http
+GET /api/v1/my/say-hello
+```
+
+5. Authenticate via the **Authorize** button.
+
+6. Once authenticated try out the endpoint via the **Try it out** button and then click on **Execute**:
+
+![Trying out the endpoint](./images/custom-api-swagger-example-response.png)
+
+Here we get the response we have setup via code: `"Hello, {{userName}}"`.

14/umbraco-cms/reference/management-api/README.md

@@ -0,0 +1,84 @@
+---
+description: Get started with the Management API.
+---
+
+# Management API
+
+The Management API delivers headless capabilities built directly into Umbraco. In comparison with the Content Delivery API, Management API allows you to interact with everything else from the backoffice apart from the content and media items. You can then receive responses in a JSON format and lets you preset them in different channels, using your preferred technology stack. This feature preserves the friendly editing experience of Umbraco, while also ensuring a performant delivery of content in a headless fashion. And with its different extension points, you can tailor this API to fit a broad range of requirements.
+
+The Management API can also be used for custom apps or workflows with OpenID Connect.
+
+{% hint style="info" %}
+The Management API is a replacement for the backoffice controllers that were not restful.
+{% endhint %}
+
+## Swagger Documentation
+
+Umbraco ships with Swagger to document the Management API. Swagger and the Swagger UI are based on [Swashbuckle.AspNetCore](https://github.com/domaindrivendev/Swashbuckle.AspNetCore/) and is available at `{yourdomain}/umbraco/swagger`. For security reasons, both are disabled in non-production environments.
+Read more about Swagger in the [API versioning and OpenAPI](../api-versioning-and-openapi.md) article.
+
+From the Swagger documentation you can select a definition to navigate to Umbraco Management API or the Content Delivery API. You can also create a custom documentation in the swagger which you can read more about in the [Custom Swagger API with Authorization](../../extending-cms/custom-swagger-api.md) article.
+
+![Umbraco Management API documentation in Swagger](../images/management-api-swagger.png)
+
+In the Swagger Umbraco Management API you can find a collection of the available endpoints in this version of Umbraco. It also includes all the legacy APIs that are available for backward compatibility.
+
+## Authorization
+
+The Management API endpoints are protected by the backoffice authorization policy and need an authentication token to interact with them.
+
+To setup the authorization, click on **Authorize** button:
+
+![Umbraco Management API Authorize Button](../images/management-api-swagger-authorize-button.png)
+
+Then a popup will appear with some setup information and login form for authorization:
+
+![Umbraco Management API Authorize Login](../images/management-api-swagger-authorize-instructions.png)
+
+The available integration for the authorization is done via a backoffice user with the integration of **OAuth2, authorizationCode with PKCE**. If you are working on a production environment, you will need to setup an OAuth2 integration with the following Umbraco Authentication specifications:
+
+**Authorization URL**
+
+```http
+{yourdomain}/umbraco/management/api/v1/security/back-office/authorize
+```
+
+**Token URL**
+
+```http
+{yourdomain}/umbraco/management/api/v1/security/back-office/token
+```
+
+**Flow**
+
+```http
+authorizationCode with PKCE
+```
+
+**client_id**
+
+```http
+umbraco-swagger
+```
+
+You can see an example of how to setup OAuth2 with Postman in the [Swagger Setup in Postman](./postman-setup-swagger) article.
+
+## Test an Endpoint
+
+In order to test a Management API endpoint, follow these steps: , authorize localhost then click on the first endpoint , execute check response 200- then click
+
+1. Authenticate via the **Authorize** button. On a development environment you need only a `client_id` which has a default value of `umbraco-swagger` to login. Then click **Authorize** and you will be logged in:
+
+![Umbraco Management API when Authenticated](../images/management-api-swagger-authenticated.png)
+
+2. Expand the first endpoint of **Audit Log** and click **Try it out**
+
+![Umbraco Management API Endpoint - Try it Out Button](../images/management-api-try-it-out.png)
+
+3. Then you will have the option to change the values of the **parameters**, however in this case let´s leave the default values as they are. Now click on **Execute** so we can get some data for our **Audit Log** endpoint.
+
+![Umbraco Management API Endpoint - Execute - Response](../images/management-api-execute-response.png)
+
+In the **Response Body** we get the details of the **Audit Log** that we have requested.
+
+4. You can continue changing the default **parameters**, **clear** the query or **cancel** the trial of the endpoint.