企業

Optimizely CMS での Scalar の使用

OpenAPI、Content Delivery API、および最新の API ドキュメント最新の Optimizely CMS ソリューションはますます API ファーストになっています。ヘッドレスフロントエンドを構築している場合でも、外部サービスを統合している場合でも、内部プラットフォーム API を公開している場合でも、明確で発見可能な API コントラクトが不可欠です。 .NET 8 では、API ドキュメントの処理方法が微妙に、しかし重要に変更されたため、これはさらに重要になります。この記事ではその組み合わせ方を紹介しますオープンAPI、スカラー、そして CMSを最適化するクリーンで将来性のある API ドキュメントのセットアップを作成します。カスタム API、Optimizely Content Delivery、およびすべてが単一の開発者向け UI にどのように組み合わされるかを見ていきます。完全な動作例はここから入手できます。github.com/andreas-valtech/OptimizelyScalarContentdelivery Swagger UI、.NET…

執筆 nipponese 更新 2026年2月7日

1770482881
2026-02-06 09:59:00

OpenAPI、Content Delivery API、および最新の API ドキュメント

最新の Optimizely CMS ソリューションはますます API ファーストになっています。ヘッドレスフロントエンドを構築している場合でも、外部サービスを統合している場合でも、内部プラットフォーム API を公開している場合でも、 明確で発見可能な API コントラクト が不可欠です。 .NET 8 では、API ドキュメントの処理方法が微妙に、しかし重要に変更されたため、これはさらに重要になります。

この記事ではその組み合わせ方を紹介します オープンAPI、 スカラー、そして CMSを最適化する クリーンで将来性のある API ドキュメントのセットアップを作成します。カスタム API、Optimizely Content Delivery、およびすべてが単一の開発者向け UI にどのように組み合わされるかを見ていきます。

完全な動作例はここから入手できます。
github.com/andreas-valtech/OptimizelyScalarContentdelivery

Swagger UI、.NET 8、および実際の変更点

.NET 8 以降にアップグレードすると、多くのチームは、Swagger UI が新しい ASP.NET Core プロジェクトに自動的に表示されなくなったことに気づきます。これは何かが削除されたように感じるかもしれませんが、実際には意図的なアーキテクチャの変更を反映しています。

最近の ASP.NET Core バージョンでは、Microsoft は分離しました OpenAPI ドキュメントの生成 から API ドキュメントのユーザーインターフェイス。このフレームワークは現在、標準に準拠した OpenAPI 仕様の作成に重点を置いていますが、UI の選択は完全にアプリケーションに任されています。 Swagger UI は、Swashbuckle などのライブラリを通じて引き続き完全にサポートされていますが、デフォルトとはみなされなくなりました。

この分離により、次の重要な考え方が強化されます。 OpenAPI は UI ではなくコントラクトです。そのコントラクトが存在すると、Swagger UI、Scalar、またはその他の互換性のあるツールを使用してレンダリングできます。カスタム API、コンテンツ配信、検索、外部統合が共存することが多い Optimizely CMS ソリューションにとって、この柔軟性は明らかな利点です。

.NET 8でのOpenAPIの生成

Swashbuckle は、ASP.NET Core で OpenAPI ドキュメントを生成する最も一般的な方法です。

を追加した後、 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() この呼び出しは、ASP.NET Core の Microsoft の OpenAPI サポートから来ており、生成された OpenAPI ドキュメントを JSON として公開する役割を果たします。ユーザーインターフェイスは提供されません。スカラーは別途追加され、そのスカラーを使用します。 MapScalarApiReference() 拡張メソッドを使用して、そのコントラクトの上に API ドキュメント UI を構築します。これには、アプリケーションで定義されているすべての API コントローラーと、プロジェクトに追加された外部 OpenAPI (swagger.json) ドキュメント (Optimizely や他のサービスによって提供されるものなど) が含まれます。このように、ASP.NET Core が OpenAPI 仕様の生成を担当し、Scalar は内部 API と外部 API の両方を単一の統一されたビューで表示する責任を負います。

API ドキュメント UI としてのスカラー

Scalar は、同じ OpenAPI JSON を使用しますが、よりクリーンで高速、より開発者重視の方法でそれを表示する最新の OpenAPI UI です。 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 ですぐに表示されます。

Optimizely Content Delivery API の導入

Optimizely は、コンテンツ配信 API 用の公式 OpenAPI (swagger.json) 定義を提供しています。これらは、Optimizely 開発者ドキュメントからダウンロードできます。

https://docs.developers.optimizely.com/content-management-system/v1.5.0-content-delivery-api/reference/content-delivery-class-libraries-and-apis

これらの JSON ファイルをプロジェクトに直接追加し、静的な OpenAPI ドキュメントとして提供することで、Scalar は Optimizely の API を独自の API と並べて表示できます。これにより、フロントエンド開発者と統合開発者がカスタムエンドポイントとコンテンツ配信エンドポイントの両方を 1 か所で探索できる単一の API サーフェスが作成されます。

Content Delivery API はヘッドレス Optimizely ソリューションの中心であり、ページ、ブロック、コンテンツ構造を JSON として公開します。明示的に文書化すると、コンテンツ契約がより明確になり、バックエンドチームとフロントエンドチーム間の摩擦が軽減されます。

コンテンツ管理 API とコンテンツ検索 API

コンテンツ配信に加えて、Optimizely のコンテンツ管理 API とコンテンツ検索 API は、多くの場合、大規模な統合および自動化ワークフローの一部です。 OpenAPI 定義を同じドキュメント UI に含めることで、開発者の内部エクスペリエンスが向上し、検索クエリ、フィルター、応答構造を推論しやすくなります。

Scalar は複数の OpenAPI ドキュメントを適切に処理するため、Optimizely ベースのプラットフォームの軽量の内部 API ポータルとして適しています。

外部 API と統合 API ビュー

Optimizely ソリューションの多くは、コマースプラットフォーム、DAM システム、パーソナライゼーションエンジンなどの外部サービスと統合されています。これらのサービスが OpenAPI 定義を提供する場合、それらを Optimizely およびカスタム API と一緒に含めることができ、チームに単一の一貫したドキュメントエクスペリエンスを提供します。

サンプルリポジトリ

これらすべては、実行可能な .NET 8 の例で示されています。
https://github.com/andreas-valtech/OptimizelyScalarContentdelivery/

次のステップ: Keycloak による認証

この記事では、認証されていない API に焦点を当てます。シリーズの次のパートでは、を使用した認証について紹介します。 キークロークOAuth 2.0 と OpenID Connect について説明し、カスタム API と Optimizely Content Delivery エンドポイントの両方を保護し、OpenAPI と Scalar の認証フローを文書化します。

最後に

OpenAPI をプライマリコントラクトとして扱い、Scalar のような最新の UI を使用することにより、Optimizely CMS ソリューションは ASP.NET Core および最新のヘッドレスアーキテクチャの方向性と自然に一致します。その結果、API がより明確になり、開発者エクスペリエンスが向上し、プラットフォームのコンポーザブル化に合わせて拡張可能なセットアップが実現します。

2026 年 2 月 6 日

#Optimizely #CMS #での #Scalar #の使用

執筆者について: nipponese

Nipponese News編集部は、国内外のニュースを日本語で分かりやすくお届けします。