> ## Documentation Index
> Fetch the complete documentation index at: https://docs.diyanet.pro/llms.txt
> Use this file to discover all available pages before exploring further.

# OpenAPI, Swagger & Scalar

> NSwag document generation, üç security scheme, Keycloak login, client üretimi

API dokümantasyonu **NSwag** (`NSwag.AspNetCore`) ile üretilir. İki ayrı görüntüleyici sunulur: klasik **Swagger UI** ve modern **Scalar** (`Scalar.AspNetCore`). OpenAPI dökümanı `builder.Services.AddOpenApiDocument(...)` ile yapılandırılır (`Program.cs`).

## Üç security scheme

Swagger dökümanına üç güvenlik şeması eklenir. Her endpoint'e üçü de otomatik uygulanır (`AspNetCoreOperationSecurityScopeProcessor`):

| Scheme             | Tür                                | Açıklama                                                    |
| ------------------ | ---------------------------------- | ----------------------------------------------------------- |
| `Bearer`           | HTTP Bearer                        | Uygulamanın kendi JWT'si. "Bearer {token}"                  |
| `KeycloakVatandas` | OAuth2 (Authorization Code + PKCE) | Vatandaş / Website client (`diyanet-website`), 2 saat token |
| `KeycloakPersonel` | OAuth2 (Authorization Code + PKCE) | Personel / Admin client (`diyanet-admin`), 5 dakika token   |

Her iki Keycloak scheme'i, ilgili realm'in `protocol/openid-connect/auth` ve `token` endpoint'lerini kullanır. URL'ler config'ten okunur:

```csharp theme={null}
var kcWebsiteBase  = builder.Configuration["Keycloak:Vatandas:PublicBaseUrl"]
                     ?? builder.Configuration["Keycloak:Vatandas:BaseUrl"]
                     ?? "http://localhost:8080";
// → {base}/realms/{realm}/protocol/openid-connect/auth  (ve /token)
```

<Note>
  `PublicBaseUrl`, tarayıcının (Swagger UI'ı açan istemci) ulaşabileceği adrestir. Docker dev'de API container'ı Keycloak'a `http://diyanet-keycloak:8080` ile bağlanır ama tarayıcı `http://localhost:8080`'e gider — bu yüzden Swagger URL'lerinde `PublicBaseUrl` (external) kullanılır, `BaseUrl` (internal) değil.
</Note>

## Swagger üzerinden Keycloak login

Swagger UI'daki **Authorize** butonu, PKCE ile doğrudan Keycloak login sayfasını açacak şekilde önyapılandırılmıştır:

```csharp theme={null}
option.OAuth2Client = new OAuth2ClientSettings
{
    ClientId     = kcPersonelClientId,   // varsayılan: personel client'ı açılır
    ClientSecret = "",                   // public client (PKCE) — secret boş
    UsePkceWithAuthorizationCodeGrant = true,
    AdditionalQueryStringParameters = { { "kc_locale", "tr" } }  // Türkçe login
};
```

Varsayılan olarak personel client'ı açılır. Vatandaş endpoint'lerini test etmek için Swagger UI'da `KeycloakVatandas` scheme'ini ayrıca authorize et. Keycloak realm provisioning, Swagger redirect URI'larını (`http://localhost:5005/swagger/oauth2-redirect.html` vb.) client'a ekler.

## Ortama göre erişim

```csharp theme={null}
if (app.Environment.IsDevelopment() || app.Environment.IsStaging())
{
    app.MapOpenApi();
    app.UseOpenApi();
    app.UseSwaggerUi(...);            // Swagger UI
    app.MapScalarApiReference(...);  // Scalar
}
else
{
    app.MapScalarApiReference().RequireAuthorization();  // Prod: auth zorunlu
}
```

| Ortam       | Swagger UI | Scalar                   |
| ----------- | ---------- | ------------------------ |
| Development | Açık       | Açık                     |
| Staging     | Açık       | Açık                     |
| Production  | Kapalı     | `RequireAuthorization()` |

Dev'de erişim (host port `5005`):

```text theme={null}
http://localhost:5005/swagger        → Swagger UI
http://localhost:5005/scalar/v1      → Scalar
http://localhost:5005/swagger/v1/swagger.json → OpenAPI JSON
```

<Note>
  `IgnoreNonPublicSchemaProcessor` (`SeedWork/NSwag/`) yalnızca public property'lerin şemaya dahil edilmesini sağlar — internal/private alanlar OpenAPI çıktısına sızmaz.
</Note>

## SPA'larda client üretimi

Her iki SPA, NSwag CLI'ı ile typed Axios client üretir. `npm run generate-api` script'i (`package.json`):

```bash theme={null}
nswag openapi2tsclient \
  /input:http://localhost:5005/swagger/v1/swagger.json \
  /output:src/lib/api-client.ts \
  /template:Axios \
  /generateClientClasses:true \
  /httpClientType:Axios
```

API çalışırken bu komut çalıştırılır; OpenAPI JSON'dan TypeScript Axios client class'ları üretilip `src/lib/api-client.ts`'e yazılır.

## Sonraki adımlar

<CardGroup cols={2}>
  <Card title="Controller'lar" href="/api/controllers">
    Endpoint'ler ve ProblemDetails hata yanıtları.
  </Card>

  <Card title="Frontend SPA'lar" href="/api/frontend">
    Üretilen client'ın axios instance'a bağlanması.
  </Card>

  <Card title="Keycloak" href="/keycloak/overview">
    Çift realm, OAuth2 + PKCE detayları.
  </Card>

  <Card title="API genel bakış" href="/api/overview">
    NSwag kayıt sırası ve pipeline.
  </Card>
</CardGroup>