OpenAPI, API доставки контента и документация по современному API
Современные решения Optimizely CMS все чаще ориентированы на API. Независимо от того, создаете ли вы автономный интерфейс, интегрируете внешние сервисы или предоставляете доступ к внутренним API-интерфейсам платформы, имея понятные и доступные для обнаружения контракты API имеет важное значение. В .NET 8 это становится еще более актуальным, поскольку способ обработки документации API слегка, но существенно изменился.
В этой статье показано, как объединить OpenAPI, Скаляри Оптимизировать CMS для создания чистой, перспективной настройки документации API. Мы рассмотрим пользовательские API, Optimizely Content Delivery и то, как все это сочетается в едином удобном для разработчиков пользовательском интерфейсе.
Полный рабочий пример доступен здесь:
github.com/andreas-valtech/OptimizelyScalarContentDelivery
Пользовательский интерфейс Swagger, .NET 8 и что на самом деле изменилось
При обновлении до .NET 8+ многие команды замечают, что пользовательский интерфейс Swagger больше не появляется автоматически в новых проектах ASP.NET Core. Может показаться, что что-то было удалено, но на практике это отражает преднамеренный архитектурный сдвиг.
В последних версиях ASP.NET Core Microsoft разделила Генерация документов OpenAPI от Пользовательские интерфейсы документации API. Теперь фреймворк фокусируется на создании спецификации OpenAPI, соответствующей стандартам, оставляя при этом выбор пользовательского интерфейса полностью на усмотрение приложения. Пользовательский интерфейс Swagger по-прежнему полностью поддерживается такими библиотеками, как Swashbuckle, но больше не предполагается, что он используется по умолчанию.
Это разделение усиливает важную идею: OpenAPI — это контракт, а не пользовательский интерфейс. Как только этот контракт существует, его можно отобразить с помощью Swagger UI, Scalar или любого другого совместимого инструмента. Для решений Optimizely CMS, где пользовательские API, доставка контента, поиск и внешняя интеграция часто сосуществуют бок о бок, такая гибкость является явным преимуществом.
Генерация OpenAPI в .NET 8
Swashbuckle остается наиболее распространенным способом создания документов OpenAPI в ASP.NET Core.
После добавления Swashbuckle.AspNetCore пакете, вы можете настроить генерацию OpenAPI непосредственно в Startup.cs:
public class Startup(IWebHostEnvironment webHostingEnvironment) { public void ConfigureServices(IServiceCollection services) {
... services.AddCms(); // Content Delivery API services.AddContentDeliveryApi(options => { options.SiteDefinitionApiEnabled = true; }); // Content Delivery Search API services.AddContentSearchApi(options => { options.MaximumSearchResults = 10; }); // Swashbuckle services.AddEndpointsApiExplorer(); services.AddSwaggerGen(); } public void Configure(IApplicationBuilder app, IWebHostEnvironment env) { ... app.UseSwagger(); app.UseSwaggerUI(); app.UseEndpoints(endpoints => { endpoints.MapContent(); // Maps both Content Delivery API and Commerce Content Delivery API endpoints.MapSwagger("/openapi/{documentName}.json", options => { options.OpenApiVersion = OpenApiSpecVersion.OpenApi3_1; }); endpoints.MapScalarApiReference(options => { options.WithTitle("Alloy Example API"); }); }); } }
На этом этапе стоит уточнить, что происходит в пайплайне. MapSwagger() Вызов исходит от поддержки Microsoft OpenAPI в ASP.NET Core и отвечает за представление сгенерированного документа OpenAPI в формате JSON. Он не предоставляет никакого пользовательского интерфейса. Скаляр добавляется отдельно и использует свой MapScalarApiReference() метод расширения для создания пользовательского интерфейса документации API поверх этого контракта. Сюда входят все контроллеры API, определенные в приложении, а также любые внешние документы OpenAPI (swagger.json), добавленные в проект, например, предоставленные Optimizely или другими службами. Таким образом, ASP.NET Core отвечает за создание спецификации OpenAPI, а Scalar отвечает за представление как внутренних, так и внешних API в едином унифицированном представлении.
Скаляр как пользовательский интерфейс документации API
Scalar — это современный пользовательский интерфейс OpenAPI, который использует тот же OpenAPI JSON, но представляет его более чистым, быстрым и более ориентированным на разработчиков способом. Поскольку Scalar зависит только от спецификации OpenAPI, он идеально соответствует направлению, выбранному ASP.NET Core.
Чтобы настроить скаляр, вы можете воспользоваться руководством по началу работы с ASP.NET Core здесь: https://scalar.com/products/api-references/integrations/aspnetcore/integration или используйте мой связанный проект GitHub для справки.
После подключения Scalar он автоматически отображает все, что описано в вашем документе OpenAPI, включая пользовательские контроллеры, схемы и определения аутентификации.
Чтобы убедиться, что все работает, достаточно простого контроллера:
[ApiController] [Route("api/hello")] public class HelloController : ControllerBase { [HttpGet] public IActionResult Get() => Ok(new { message = "Hello from Optimizely + Scalar" }); }
Эта конечная точка обнаруживается автоматически, включается в документ OpenAPI и сразу же отображается в Scalar без какой-либо дополнительной настройки.
Использование API доставки контента Optimizely
Optimizely предоставляет официальные определения OpenAPI (swagger.json) для своих API доставки контента. Их можно скачать из документации разработчика Optimizely:
Добавляя эти файлы JSON непосредственно в ваш проект и предоставляя их в качестве статических документов OpenAPI, Scalar может отображать API Optimizely рядом с вашими собственными. Это создает единую поверхность API, где разработчики внешнего интерфейса и интеграции могут исследовать как пользовательские конечные точки, так и конечные точки доставки контента в одном месте.
API доставки контента занимает центральное место в автономных решениях Optimizely, предоставляя страницы, блоки и структуры контента в формате JSON. Явное документирование делает контракты на контент более понятными и снижает трения между бэкэнд- и фронтенд-командами.
API управления контентом и поиска контента
Помимо доставки контента, API-интерфейсы Optimizely для управления контентом и поиска контента часто являются частью более крупных интеграций и рабочих процессов автоматизации. Включение их определений OpenAPI в один и тот же пользовательский интерфейс документации улучшает работу внутренних разработчиков и упрощает понимание поисковых запросов, фильтров и структур ответов.
Scalar хорошо обрабатывает несколько документов OpenAPI, что делает его подходящим в качестве легкого внутреннего портала API для платформ на базе Optimizely.
Внешние API и унифицированное представление API
Многие решения Optimizely интегрируются с внешними сервисами, такими как коммерческие платформы, системы DAM или механизмы персонализации. Когда эти сервисы предоставляют определения OpenAPI, их можно включать вместе с Optimizely и пользовательскими API, предоставляя командам единый и согласованный опыт документирования.
Пример репозитория
Все это продемонстрировано на работоспособном примере .NET 8 здесь:
https://github.com/andreas-valtech/OptimizelyScalarContentDelivery/
Что дальше: аутентификация с помощью Keycloak
В этой статье основное внимание уделяется API-интерфейсам без аутентификации. В следующей части серии мы представим аутентификацию с использованием плащ-ключохватывающий OAuth 2.0 и OpenID Connect, защиту как пользовательских API, так и конечных точек доставки контента Optimizely, а также документирование потоков аутентификации в OpenAPI и Scalar.
Заключительные мысли
Рассматривая OpenAPI как основной контракт и используя современный пользовательский интерфейс, такой как Scalar, решения Optimizely CMS естественным образом соответствуют направлению ASP.NET Core и современным автономным архитектурам. Результатом являются более понятные API, лучший опыт разработчиков и настройка, которая хорошо масштабируется по мере того, как платформы становятся более компонуемыми.
6 февраля 2026 г.
Ещё по этой теме
