ASP.NET Core webes API dokumentációja a Swagger/OpenAPI használatával

Készítette : Rico Suter

Swagger (OpenAPI) egy nyelvfüggetlen specifikáció az API-k leírásához REST Lehetővé teszi, hogy a számítógépek és az emberek is megértsék az API képességeit REST anélkül, hogy közvetlenül hozzáférnek a forráskódhoz. Fő céljai a következők:

• A leválasztott szolgáltatások csatlakoztatásához szükséges munkamennyiség minimalizálása.
• Csökkentse a szolgáltatás pontos dokumentálásához szükséges időt.

A .NET két fő OpenAPI-implementációja a Swashbuckle és az NSwag, lásd:

• A Swashbuckle használatának első lépései
• Az NSwag használatának első lépései

OpenAPI és Swagger

A Swagger-projektet 2015-ben az OpenAPI kezdeményezésnek adományozták, és azóta OpenAPI-nak nevezik. Mindkét név felcserélhető. Az "OpenAPI" azonban a specifikációra utal. A "Swagger" a SmartBear nyílt forráskódú és kereskedelmi termékeinek családjára utal, amelyek az OpenAPI specifikációval működnek együtt. A későbbi nyílt forráskódú termékek, például az OpenAPIGenerator szintén A Swagger családnév alá tartoznak, annak ellenére, hogy a SmartBear nem adta ki őket.

Röviden:

• Az OpenAPI egy specifikáció.
• A Swagger az OpenAPI-specifikációt használó eszköz. Például: OpenAPIGenerator és SwaggerUI.

OpenAPI-specifikáció (openapi.json)

Az OpenAPI-specifikáció egy olyan dokumentum, amely leírja az API képességeit. A dokumentum a vezérlőkben és modellekben található XML- és attribútumjegyzeteken alapul. Ez az OpenAPI-folyamat alapvető része, és olyan eszközök vezetésére szolgál, mint a SwaggerUI. Alapértelmezés szerint a neve openapi.json. Íme egy példa egy OpenAPI-specifikációra, amely a rövidség kedvéért csökkent:

{
  "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 felhasználói felület

A Swagger felhasználói felülete egy webes felhasználói felületet kínál, amely a létrehozott OpenAPI-specifikáció használatával nyújt információt a szolgáltatásról. A Swashbuckle és az NSwag is tartalmazza a Swagger felhasználói felületének beágyazott verzióját, így a ASP.NET Core-alkalmazásban üzemeltethető köztes szoftverregisztrációs hívással. A webes felhasználói felület a következőképpen néz ki:

A vezérlők minden nyilvános műveletmetódusa tesztelhető a felhasználói felületen. Válasszon egy metódusnevet a szakasz kibontásához. Adjon hozzá minden szükséges paramétert, és válassza a Kipróbálás!lehetőséget.

Megjegyzés:

A képernyőképekhez használt Swagger felhasználói felület verziója a 2- es verzió. A 3- es verziójú példáért lásd a Petstore-példát.

Swagger felhasználói felületi végpontok védelme

Hívás MapSwagger().RequireAuthorization a Swagger felhasználói felületi végpontok biztonságossá tételéhez. Az alábbi példa a Swagger-végpontok védelmét biztosítja:

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);
}

Az előző kódban a /weatherforecast végpontnak nincs szüksége engedélyezésre, de a Swagger-végpontok igen.

A következő Curl egy JWT-jogkivonatot ad át a Swagger felhasználói felületi végpontjának teszteléséhez:

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

A JWT-jogkivonatokkal végzett teszteléssel kapcsolatos további információkért lásd: Tokenek létrehozása dotnet user-jwts használatával.

Xml-dokumentációs fájl létrehozása fordításkor.

További információt a GenerateDocumentationFile című témakörben talál.

Következő lépések

• A Swashbuckle használatának első lépései
• Ismerkedés az NSwag szolgáltatással