ASP.NET Core web API belgeleri Swagger / OpenAPI ile

Tarafından Rico Suter

Bu makalede, ASP.NET Core web API'leri için OpenAPI belgeleri ve etkileşimli yardım sayfaları oluşturmak üzere Swashbuckle.AspNetCore ve NSwag paketleri tarafından sağlanan Swagger araçlarının kullanımı açıklanmıştır.

.NET 9 ve sonraki sürümlerde ASP.NET Core, varsayılan olarak Swashbuckle'ın yerini alan yerleşik OpenAPI desteği içerir. Swashbuckle artık proje şablonlarına dahil değildir, ancak el ile ekleyebileceğiniz bir topluluk paketi olarak kullanılabilir durumda kalır.

• Yerleşik OpenAPI özelliklerini anlamak için bkz. ASP.NET Core API uygulamalarında OpenAPI desteğine genel bakış.
• Yerleşik OpenAPI desteğine etkileşimli keşif veya yerel geçici test için Swagger kullanıcı arabirimi eklemek için bkz. Oluşturulan OpenAPI belgelerini kullanma.

Aşağıdaki yönergeler, ASP.NET Core 8.0 ve önceki sürümlerine sahip Swashbuckle veya NSwag kullanan projeler için geçerlidir.

Swagger (OpenAPI), API'leri açıklamaya REST yönelik dilden bağımsız bir belirtimdir. Hem bilgisayarların hem de insanların kaynak koda doğrudan erişim olmadan API'nin REST özelliklerini anlamasını sağlar. Başlıca hedefleri şunlardır:

• Ayrılmış hizmetleri bağlamak için gereken çalışma miktarını en aza indirin.
• Bir hizmeti doğru bir şekilde belgeleyemek için gereken süreyi azaltın.

.NET için iki ana OpenAPI uygulaması Swashbuckle ve NSwag'dır, bkz:

• Swashbuckle'ı Kullanmaya Başlama
• NSwag'ı Kullanmaya Başlama

OpenAPI ve Swagger karşılaştırması

Swagger projesi 2015 yılında OpenAPI Girişimi'ne bağışlanmıştır ve o zamandan beri OpenAPI olarak anılmaktadır. Her iki ad da birbirinin yerine kullanılır. "Ancak, 'OpenAPI' terimi belirtimi ifade eder." "Swagger", OpenAPI Belirtimi ile çalışan SmartBear'ın açık kaynak ve ticari ürün ailesini ifade eder. OpenAPIGenerator gibi sonraki açık kaynak ürünler de SmartBear tarafından yayınlanmasa da Swagger ailesi adının altına girer.

Kısaca:

• OpenAPI bir belirtimdir.
• Swagger, OpenAPI belirtimini kullanan araçlardır. Örneğin, OpenAPIGenerator ve SwaggerUI.

OpenAPI belirtimi (openapi.json)

OpenAPI belirtimi, API'nizin özelliklerini açıklayan bir belgedir. Belge, denetleyiciler ve modeller içindeki XML ve öznitelik ek açıklamalarını temel alır. OpenAPI akışının temel bölümüdür ve SwaggerUI gibi araçları yönlendirmek için kullanılır. Varsayılan olarak, olarak adlandırılır openapi.json. Aşağıda, kısa kullanım için azaltılmış bir OpenAPI belirtimi örneği verilmişti:

{
  "openapi": "3.0.1",
  "info": {
    "title": "API V1",
    "version": "v1"
  },
  "paths": {
    "/api/Todo": {
      "get": {
        "tags": [
          "Todo"
        ],
        "operationId": "ApiTodoGet",
        "responses": {
          "200": {
            "description": "Success",
            "content": {
              "text/plain": {
                "schema": {
                  "type": "array",
                  "items": {
                    "$ref": "#/components/schemas/ToDoItem"
                  }
                }
              },
              "application/json": {
                "schema": {
                  "type": "array",
                  "items": {
                    "$ref": "#/components/schemas/ToDoItem"
                  }
                }
              },
              "text/json": {
                "schema": {
                  "type": "array",
                  "items": {
                    "$ref": "#/components/schemas/ToDoItem"
                  }
                }
              }
            }
          }
        }
      },
      "post": {
        …
      }
    },
    "/api/Todo/{id}": {
      "get": {
        …
      },
      "put": {
        …
      },
      "delete": {
        …
      }
    }
  },
  "components": {
    "schemas": {
      "ToDoItem": {
        "type": "object",
        "properties": {
          "id": {
            "type": "integer",
            "format": "int32"
          },
          "name": {
            "type": "string",
            "nullable": true
          },
          "isCompleted": {
            "type": "boolean"
          }
        },
        "additionalProperties": false
      }
    }
  }
}

Swagger Kullanıcı Arabirimi

Swagger kullanıcı arabirimi , oluşturulan OpenAPI belirtimini kullanarak hizmet hakkında bilgi sağlayan web tabanlı bir kullanıcı arabirimi sunar. Hem Swashbuckle hem de NSwag, bir ara yazılım kayıt çağrısı kullanılarak ASP.NET Core uygulamanızda barındırılabilmesi için Swagger kullanıcı arabiriminin eklenmiş bir sürümünü içerir. Web kullanıcı arabirimi şöyle görünür:

Denetleyicilerinizdeki her genel eylem yöntemi kullanıcı arabiriminden test edilebilir. Bölümü genişletmek için bir yöntem adı seçin. Gerekli parametreleri ekleyin ve Deneyin! öğesini seçin.

Not

Ekran görüntüleri için kullanılan Swagger UI sürümü sürüm 2'dir. Sürüm 3 örneği için bkz . Petstore örneği.

Swagger UI uç noktalarının güvenliğini sağlama

Swagger UI uç noktalarının güvenliğini sağlamak için MapSwagger().RequireAuthorization çağırın. Aşağıdaki örnek, swagger uç noktalarının güvenliğini sağlar:

using System.Security.Claims;

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddEndpointsApiExplorer();
builder.Services.AddSwaggerGen();

builder.Services.AddAuthorization();
builder.Services.AddAuthentication("Bearer").AddJwtBearer();

var app = builder.Build();

  if (app.Environment.IsDevelopment())
  {
    app.UseSwagger();
    app.UseSwaggerUI();
  }

app.UseHttpsRedirection();

var summaries = new[]
{
    "Freezing", "Bracing", "Chilly", "Cool", "Mild", "Warm", "Balmy", "Hot", "Sweltering", "Scorching"
};

app.MapSwagger().RequireAuthorization();

app.MapGet("/", () => "Hello, World!");
app.MapGet("/secret", (ClaimsPrincipal user) => $"Hello {user.Identity?.Name}. My secret")
    .RequireAuthorization();

app.MapGet("/weatherforecast", () =>
{
    var forecast = Enumerable.Range(1, 5).Select(index =>
        new WeatherForecast
        (
            DateOnly.FromDateTime(DateTime.Now.AddDays(index)),
            Random.Shared.Next(-20, 55),
            summaries[Random.Shared.Next(summaries.Length)]
        ))
        .ToArray();
    return forecast;
})
.WithName("GetWeatherForecast")
.WithOpenApi();

app.Run();

internal record WeatherForecast(DateOnly Date, int TemperatureC, string? Summary)
{
    public int TemperatureF => 32 + (int)(TemperatureC / 0.5556);
}

Yukarıdaki kodda uç noktanın /weatherforecast yetkilendirmeye ihtiyacı yoktur, ancak Swagger uç noktaları bunu yapar.

Aşağıdaki Curl, Swagger UI uç noktasını test etmek için bir JWT belirteç geçirir:

curl -i -H "Authorization: Bearer {TOKEN}" https://localhost:{PORT}/swagger/v1/swagger.json

{TOKEN} burada yer tutucu taşıyıcı belirteci, JWT{PORT} yer tutucu ise bağlantı noktası numarasıdır.

Belirteçlerle JWT test etme hakkında daha fazla bilgi için bkz. dotnet user-jwts ile belirteç oluşturma.

Derleme zamanında XML belge dosyası oluşturma

Daha fazla bilgi için bkz . GenerateDocumentationFile .

Sonraki adımlar

• Swashbuckle kullanmaya başlama
• NSwag Kullanmaya Başlama