# Intent.AspNetCore.Scalar

This module installs and configures `Microsoft.AspNetCore.OpenApi` and integrates with [Scalar](https://scalar.com/) 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](https://scalar.com/) or [GitHub](https://github.com/scalar/scalar).

## 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:

```jsonc
{
  "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.

```jsonc
{
  "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"
      }
    }
  }
}
```