adding management api docs with some examples

14/umbraco-cms/SUMMARY.md

@@ -55,6 +55,12 @@
   * [Route Registration](extending-backoffice/modals/route-registration.md)
 * [Sorting](extending-backoffice/sorting.md)
 
+## Reference
+
+* [Management API](./reference/management-api/README.md)
+  * [Setup Authorization in Postman](./reference/management-api/postman-setup-swagger.md)
+* [Custom Swagger API](./reference/custom-swagger-api.md)
+
 ## Tutorials
 
 * [Creating a Basic Website](tutorials/creating-a-basic-website/README.md)

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

@@ -0,0 +1,202 @@
+---
+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 protected by the backoffice authorization policies. It also shows how to enable the authorization UI in Swagger docs.
+
+
+{% hint style="info" %}
+
+Before  proceeding, make sure to read the [Management API](./management-api/README.md) article. It provides information about the Swagger documentation and Authorization used in this article.
+
+{% endhint %}
+
+This example can be a starting point for creating a secure custom API with automatic Swagger documentation. You can find other examples in the [API versioning and OpenAPI](./api-versioning-and-openapi.md) article.
+
+1. Create a new `.cs` file called `MyBackOfficeSecurityRequirementsOperationFilter` in your Umbraco project.
+
+2. 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 Microsoft.Extensions.Options;
+using Microsoft.OpenApi.Models;
+using Swashbuckle.AspNetCore.SwaggerGen;
+using Umbraco.Cms.Api.Management.OpenApi;
+using Umbraco.Cms.Core.Composing;
+
+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>();
+}
+
+```
+
+{% endcode %}
+
+- Our filter inherits from `BackOfficeSecurityRequirementsOperationFilterBase`. This marks our API as supporting authorization via Swagger.
+- `MyConfigureSwaggerGenOptions` configures our API swagger docs with our filter applied.
+- `MyComposer ` makes sure the swagger generator knows about our API docs configuration at runtime.
+
+3. Add the ApiController to setup the logic behind the endpoint:
+
+{% code title="MyBackOfficeSecurityRequirementsOperationFilter.cs" lineNumbers="true" %}
+
+```csharp
+
+using Umbraco.Cms.Api.Common.Attributes;
+using Umbraco.Cms.Api.Common.Filters;
+using Umbraco.Cms.Core;
+using Umbraco.Cms.Core.Models.Membership;
+using Umbraco.Cms.Core.Security;
+using Umbraco.Cms.Web.Common.Authorization;
+using Asp.Versioning;
+using Microsoft.AspNetCore.Authorization;
+using Microsoft.AspNetCore.Mvc;
+...
+
+//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>
+
+<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>
+
+4. Run the project and navigate to `{yourdomain}/umbraco/swagger`.
+5. Choose the swagger documentation we created with the code above named **My API v1** from **Select a definition**.
+
+![Created Custom API in Swagger Documentation](./images/custom-api-swagger-example.png)
+
+Here, we can find the endpoint that we created:
+
+```http
+GET /api/v1/my/say-hello
+```
+
+6. Click on the **Authorize** button to authenticate.
+
+7. Try out the endpoint using the **Try it out** button.
+8. Click on **Execute**.
+
+![Trying out the endpoint](./images/custom-api-swagger-example-response.png)
+
+We now get the response we have setup using the code: `"Hello, {{userName}}"`.

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

@@ -0,0 +1,71 @@
+---
+description: Get started with the Management API.
+---
+
+# Management API
+
+The Management API delivers headless management capabilities built directly into Umbraco. The Management API is used by the backoffice to communicate with the backend.
+
+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 lacked RESTful capabilities.
+{% 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.
+
+The Swagger documentation allows you to select a definition and go to either Umbraco Management API or Content Delivery API. If you are extending the Management API with your own controllers, you can also create custom documentation for these in Swagger. See [Custom Swagger API](../custom-swagger-api.md) article for details.
+
+![Umbraco Management API documentation in Swagger](../images/management-api-swagger.png)
+
+In the Swagger Umbraco Management API, you can find a collection of available endpoints in this version of Umbraco.
+
+## Authorization
+
+The Management API endpoints are protected by the backoffice authorization policies and need an authentication token to interact with them.
+
+To set the authorization, click on the **Authorize** button:
+
+![Umbraco Management API Authorize Button](../images/management-api-swagger-authorize-button.png)
+
+Then a popup will appear with some setup information and a 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`. Swagger is only enabled in non-production environments, so if you need to access the Management API in production, you need a different client.
+
+{% hint style="info" %}
+
+In production environment, only `umbraco-back-office` **client** is allowed to connect to the Management API. In non-production environments, the `umbraco-swagger` and `umbraco-postman` **clients** can be used.
+
+You can see an example of how to connect a backoffice user via OAuth2 in Postman in the [Swagger Setup in Postman](./postman-setup-swagger) article.
+
+{% endhint %}
+
+
+# Test an Endpoint
+
+To test a Management API endpoint, follow these steps:
+
+1. Authenticate via the **Authorize** button. Make sure you use `umbraco-swagger` as the `client_id`:
+
+![Umbraco Management API when Authenticated](../images/management-api-swagger-authenticated.png)
+
+{% hint style="info" %}
+In non-production environments, you will always need only the `client_id` to authenticate. The `client_secret` should always be left blank, as the authentication flow does not use a client secret. 
+{% endhint %}
+
+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. You now have the option to change the values of the **parameters**. In this case, let´s leave the default values as they are. 
+4. Click on **Execute** so that 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.
+
+5. You can continue changing the default **parameters**, **clear** the query, or **cancel** the trial of the endpoint.