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

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

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.

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:

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

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

http://localhost:5005/swagger        → Swagger UI
http://localhost:5005/scalar/v1      → Scalar
http://localhost:5005/swagger/v1/swagger.json → OpenAPI JSON

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

SPA’larda client üretimi

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

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

Controller'lar

Endpoint’ler ve ProblemDetails hata yanıtları.

Frontend SPA'lar

Üretilen client’ın axios instance’a bağlanması.

Keycloak

Çift realm, OAuth2 + PKCE detayları.

API genel bakış

NSwag kayıt sırası ve pipeline.