5 |
6 |
7 | # Umbraco Delivery Api Extensions
8 |
9 | [](https://www.nuget.org/packages/Umbraco.Community.DeliveryApiExtensions/)
10 | [](https://www.nuget.org/packages/Umbraco.Community.DeliveryApiExtensions)
11 | [](../LICENSE)
12 |
13 | Extensions for the Umbraco Delivery API.
14 |
15 | ## Features ✨
16 |
17 | ### Backoffice preview
18 | Preview the Delivery API responses from the backoffice content/media nodes.
19 |
20 | 
21 |
22 | ### Typed swagger
23 | Adds types to the Umbraco swagger based on your document and data types (just like Models Builder), so that you can more seamlessly generate typed clients.
24 |
25 | Example of a Node console app using the types/functions generated by a typescript restful client generator using the typed swagger.
26 | ```ts
27 | import { getContentItemByPath } from './api/umbraco-api';
28 |
29 | const content = (await getContentItemByPath('/')).data;
30 |
31 | // Content can be of any document type here
32 |
33 | if (content.contentType === 'home') {
34 | // By checking the contentType, Typescript knows this is a Home page
35 | // and properly validates the properties and their types
36 | console.log(`Name: ${content.name}`);
37 | console.log(`Title: ${content.properties?.title}`);
38 | console.log(`Text: ${content.properties?.text?.markup}`);
39 | }
40 | ```
41 |
42 | 
43 |
44 | ## Installation 🧑💻
45 |
46 | Add the package to an existing Umbraco website (v12.2+) from nuget:
47 |
48 | ```sh
49 | dotnet add package Umbraco.Community.DeliveryApiExtensions
50 | ```
51 |
52 | ### Configuration (appsettings.json)
53 |
54 | The following represents the default configuration, which can optionally be overriden by defining it in your own app settings.
55 | ```jsonc
56 | {
57 | "DeliveryApiExtensions": {
58 | "Preview": {
59 | "Enabled": true,
60 | "Media": {
61 | "Enabled": true
62 | },
63 | "AllowedUserGroupAliases": [], // All allowed by default
64 | },
65 | "TypedSwagger": {
66 | "Enabled": true,
67 | "Mode": "Auto"
68 | }
69 | }
70 | }
71 | ```
72 |
73 | **Typed swagger modes**
74 |
75 | - **Automatic (Auto)** - Swagger will be generated with the `UseOneOfForPolymorphism` and `UseAllOfForInheritance` options.
76 | Suitable for most generators like [openapi-typescript](https://openapi-ts.pages.dev) and [orval](https://orval.dev).
77 |
78 | - **Compatibility** - Swagger will be generated with only the `UseAllOfForInheritance` option enabled.
79 | Suitable for generators that don't support polymorphism using OneOf like [NSwag](https://github.com/RicoSuter/NSwag).
80 |
81 | - **Manual** - Swagger options will not be configured, allowing full customization.
82 | It can be configured from your codebase using:
83 | ```csharp
84 | services.Configure
24 | /// services.Configure<SwaggerGenOptions>(options => ...)
25 | /// services.Configure<TypedSwaggerOptions>(options => ...)
26 | ///
27 | ///
28 | Could not render component of type: @(item.Content.ContentType.Alias)
29 |
30 | This likely happened because the partial view @partialViewName could not be found.
31 |
@ex.ToString()11 | } 12 | 13 | @functions{ 14 | 15 | public static string EditorView(dynamic contentItem) 16 | { 17 | string view = contentItem.editor.render != null ? contentItem.editor.render.ToString() : contentItem.editor.view.ToString(); 18 | view = view.Replace(".html", ".cshtml"); 19 | 20 | if (!view.Contains("/")) 21 | { 22 | view = "grid/editors/" + view; 23 | } 24 | 25 | return view; 26 | } 27 | } 28 | -------------------------------------------------------------------------------- /tests/UmbracoDeliveryApiExtensions.TestSite/Views/Partials/grid/editors/embed.cshtml: -------------------------------------------------------------------------------- 1 | @inherits Umbraco.Cms.Web.Common.Views.UmbracoViewPage
@Model.value.caption
63 | } 64 | } 65 | -------------------------------------------------------------------------------- /tests/UmbracoDeliveryApiExtensions.TestSite/Views/Partials/grid/editors/rte.cshtml: -------------------------------------------------------------------------------- 1 | @using Umbraco.Cms.Core.Templates 2 | @model dynamic 3 | @inject HtmlLocalLinkParser HtmlLocalLinkParser; 4 | @inject HtmlUrlParser HtmlUrlParser; 5 | @inject HtmlImageSourceParser HtmlImageSourceParser; 6 | 7 | @{ 8 | var value = HtmlLocalLinkParser.EnsureInternalLinks(Model?.value.ToString()); 9 | value = HtmlUrlParser.EnsureUrls(value); 10 | value = HtmlImageSourceParser.EnsureImageSources(value); 11 | } 12 | 13 | @Html.Raw(value) 14 | -------------------------------------------------------------------------------- /tests/UmbracoDeliveryApiExtensions.TestSite/Views/Partials/grid/editors/textstring.cshtml: -------------------------------------------------------------------------------- 1 | @model dynamic 2 | 3 | @if (Model?.editor.config.markup is not null) 4 | { 5 | string markup = Model.editor.config.markup.ToString(); 6 | markup = markup.Replace("#value#", Html.ReplaceLineBreaks((string)Model.value.ToString()).ToString()); 7 | 8 | if (Model.editor.config.style != null) 9 | { 10 | markup = markup.Replace("#style#", Model.editor.config.style.ToString()); 11 | } 12 | 13 |