Intent.AspNetCore.Scalar

This module installs and configures Microsoft.AspNetCore.OpenApi and integrates with Scalar for API documentation.

Scalar is a modern, fast, and user-friendly OpenAPI documentation viewer. It works with the new Microsoft.AspNetCore.OpenApi features introduced in .NET 9+, allowing you to generate OpenAPI documents and visualize them in an interactive UI. Scalar replaces older Swagger UI solutions such as Swashbuckle, providing a clean developer experience, native integration with ASP.NET Core, and support for OpenAPI 3.1.

With Scalar, developers can easily expose the details of their Web API, including available endpoints, request and response models, and supported HTTP methods. This makes it easier for developers and third-party consumers to understand, test, and interact with the API, promoting better communication and collaboration between frontend and backend teams.

This module specifically deals with:

• Dependency Injection wiring
• OpenAPI document generation using Microsoft.AspNetCore.OpenApi
• Scalar UI configuration

For more information on Scalar, check out their Website or GitHub.

HTTP QUERY endpoints

The HTTP QUERY method can only be described from OpenAPI 3.2. When the application targets .NET 10 and at least one operation uses the QUERY verb, the module:

• Generates HttpQueryDocumentTransformer, which adds the QUERY operations to the OpenAPI document.
• Adds app.UseHttpQueryOpenApi() to the request pipeline, which serves /openapi/{documentName}.json as OpenAPI 3.2 so Scalar can show and send QUERY requests.

On earlier .NET versions, or with no QUERY operations, none of this is generated and QUERY endpoints are left out of the OpenAPI document.

Settings

Use fully qualified schema identifiers

By default, schema identifiers have been configured to be the fully qualified type name so as to avoid conflicts with otherwise identically named types. When this option is enabled "simple" identifiers without a namespace are generated instead.

Authentication

This module supports authentication in your API documentation and can configure the OpenAPI document for the following authentication modes:

• Bearer
• OAuth 2.0 - Authorization Code
• OAuth 2.0 - Implicit

Bearer Token Authentication

Bearer authentication is automatically configured with the following security scheme:

• Scheme: bearer
• Format: JWT

This allows developers to paste a raw JWT token into the Scalar "Authorize" dialog and have it automatically included in all requests.

OAuth 2.0 - Authorization Code Authentication

When enabled, the OpenAPI document is configured with an OAuth 2.0 Authorization Code flow.

The module also applies default placeholders to appsettings.json for:

• OpenApi:Oidc:AuthorizationUrl
• OpenApi:Oidc:TokenUrl
• OpenApi:Oidc:Scopes

Update these values to match your identity provider configuration.

Example:

{
  "OpenApi": {
    "Oidc": {
      "AuthorizationUrl": "https://your-oauth-provider.com/connect/authorize",
      "TokenUrl": "https://your-oauth-provider.com/connect/token",
      "Scopes": [
        "openid",
        "profile",
        "api"
      ]
    }
  }
}

OAuth 2.0 - Implicit Authentication

⚠️ Deprecated: The Implicit flow is considered less secure than Authorization Code and is generally not recommended for new implementations.

When enabled, the OpenAPI document is configured with an OAuth 2.0 Implicit flow.

The module applies default placeholders to appsettings.json for:

• OpenApi:Oidc:AuthorizationUrl
• OpenApi:Oidc:Scopes

Update these values to match your identity provider configuration.

{
  "OpenApi": {
    "Oidc": {
      "AuthorizationUrl": "https://auth.myapp.com/connect/authorize",
      "Scopes": [
        "openid",
        "profile",
        "api"
      ]
    }
  }
}

Migration from Intent.AspNetCore.Swashbuckle

Ensure that you set your launch URL's in your launchsettings.json to scalar/v1

Example, replace https://localhost:44339/swagger with https://localhost:44339/scalar/v1

// Change this
{
  "iisSettings": {
    "windowsAuthentication": false,
    "anonymousAuthentication": true,
    "iisExpress": {
      "applicationUrl": "http://localhost:58204/",
      "sslPort": 44339
    }
  },
  "profiles": {
    "CosmosDB.Api": {
      "commandName": "Project",
      "launchBrowser": true,
      "applicationUrl": "https://localhost:44339/",
      "launchUrl": "https://localhost:44339/swagger",
      "publishAllPorts": false,
      "environmentVariables": {
        "ASPNETCORE_ENVIRONMENT": "Development"
      }
    },
    "IIS Express": {
      "commandName": "IISExpress",
      "launchBrowser": true,
      "launchUrl": "https://localhost:44339/swagger",
      "publishAllPorts": false,
      "environmentVariables": {
        "ASPNETCORE_ENVIRONMENT": "Development"
      }
    }
  }
}

// To This

{
  "iisSettings": {
    "windowsAuthentication": false,
    "anonymousAuthentication": true,
    "iisExpress": {
      "applicationUrl": "http://localhost:58204/",
      "sslPort": 44339
    }
  },
  "profiles": {
    "CosmosDB.Api": {
      "commandName": "Project",
      "launchBrowser": true,
      "applicationUrl": "https://localhost:44339/",
      "launchUrl": "https://localhost:44339/scalar/v1",
      "publishAllPorts": false,
      "environmentVariables": {
        "ASPNETCORE_ENVIRONMENT": "Development"
      }
    },
    "IIS Express": {
      "commandName": "IISExpress",
      "launchBrowser": true,
      "launchUrl": "https://localhost:44339/scalar/v1",
      "publishAllPorts": false,
      "environmentVariables": {
        "ASPNETCORE_ENVIRONMENT": "Development"
      }
    }
  }
}