Swagger / OpenAPI ile web API belgeleri ASP.NET Core

Tarafından Christoph Nienaber ve Rico Suter

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" 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 çağrısı MapSwagger().RequireAuthorization . 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 belirteci geçirir:

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

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

Derleme zamanında bir XML belge dosyası oluşturun.

Daha fazla bilgi için bkz . GenerateDocumentationFile .

Sonraki adımlar

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