Skip to main content
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):
SchemeTürAçıklama
BearerHTTP BearerUygulamanın kendi JWT’si. “Bearer “
KeycloakVatandasOAuth2 (Authorization Code + PKCE)Vatandaş / Website client (diyanet-website), 2 saat token
KeycloakPersonelOAuth2 (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
}
OrtamSwagger UIScalar
DevelopmentAçıkAçık
StagingAçıkAçık
ProductionKapalı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.