Dela via

ASP.NET Core web API-dokumentation med Swagger/OpenAPI

Av Rico Suter

Swagger (OpenAPI) är en språkagnostisk specifikation för att beskriva REST API:er. Det gör att både datorer och människor kan förstå funktionerna i ett REST API utan direkt åtkomst till källkoden. Huvudmålen är att:

  • Minimera mängden arbete som krävs för att ansluta frikopplade tjänster.
  • Minska den tid som krävs för att korrekt dokumentera en tjänst.

De två viktigaste OpenAPI-implementeringarna för .NET är Swashbuckle och NSwag, se:

OpenAPI jämfört med Swagger

Swagger-projektet donerades till OpenAPI Initiative 2015 och har sedan dess kallats OpenAPI. Båda namnen används omväxlande. "OpenAPI" refererar dock till specifikationen. "Swagger" avser familjen med öppen källkod och kommersiella produkter från SmartBear som fungerar med OpenAPI-specifikationen. Efterföljande produkter med öppen källkod, till exempel OpenAPIGenerator, faller också under Swagger-familjens namn, trots att de inte släpps av SmartBear.

Sammanfattningsvis:

  • OpenAPI är en specifikation.
  • Swagger är verktyg som använder OpenAPI-specifikationen. Till exempel OpenAPIGenerator och SwaggerUI.

OpenAPI-specifikation (openapi.json)

OpenAPI-specifikationen är ett dokument som beskriver funktionerna i ditt API. Dokumentet baseras på XML och attributanteckningar i kontrollanterna och modellerna. Det är kärnan i OpenAPI-flödet och används för att köra verktyg som SwaggerUI. Som standard heter den openapi.json. Här är ett exempel på en OpenAPI-specifikation, reducerad för korthet:

{
  "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-användargränssnitt

Swagger UI erbjuder ett webbaserat användargränssnitt som tillhandahåller information om tjänsten med hjälp av den genererade OpenAPI-specifikationen. Både Swashbuckle och NSwag innehåller en inbäddad version av Swagger-användargränssnittet, så att det kan finnas i din ASP.NET Core-app med hjälp av ett registreringsanrop för mellanprogram. Webbgränssnittet ser ut så här:

Swagger-användargränssnitt

Varje publik åtgärdsmetod i dina kontroller kan testas från användargränssnittet. Välj ett metodnamn för att expandera avsnittet. Lägg till nödvändiga parametrar och välj Prova!.

Exempel på Swagger GET-test

Anmärkning

Swagger UI-versionen som används för skärmbilderna är version 2. Ett exempel på version 3 finns i Petstore-exempel.

Skydda Swagger UI-slutpunkter

Anropa MapSwagger().RequireAuthorization för att skydda Swagger UI-slutpunkterna. Exemplet nedan visar hur du skyddar swagger-slutpunkterna:

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

I föregående kod /weatherforecast behöver slutpunkten inte auktorisering, men Swagger-slutpunkterna gör det.

Följande Curl skickar en JWT-token för att testa Swagger UI-slutpunkten:

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

Mer information om testning med JWT-token finns i Generera token med dotnet user-jwts.

Generera en XML-dokumentationsfil vid kompileringstid.

Mer information finns i GenerateDocumentationFile .

Nästa steg

Av Rico Suter

Swagger (OpenAPI) är en språkagnostisk specifikation för att beskriva REST API:er. Det gör att både datorer och människor kan förstå funktionerna i ett REST API utan direkt åtkomst till källkoden. Huvudmålen är att:

  • Minimera mängden arbete som krävs för att ansluta frikopplade tjänster.
  • Minska den tid som krävs för att korrekt dokumentera en tjänst.

De två viktigaste OpenAPI-implementeringarna för .NET är Swashbuckle och NSwag, se:

OpenAPI jämfört med Swagger

Swagger-projektet donerades till OpenAPI Initiative 2015 och har sedan dess kallats OpenAPI. Båda namnen används omväxlande. "OpenAPI" refererar dock till specifikationen. "Swagger" avser familjen med öppen källkod och kommersiella produkter från SmartBear som fungerar med OpenAPI-specifikationen. Efterföljande produkter med öppen källkod, till exempel OpenAPIGenerator, faller också under Swagger-familjens namn, trots att de inte släpps av SmartBear.

Sammanfattningsvis:

  • OpenAPI är en specifikation.
  • Swagger är verktyg som använder OpenAPI-specifikationen. Till exempel OpenAPIGenerator och SwaggerUI.

OpenAPI-specifikation (openapi.json)

OpenAPI-specifikationen är ett dokument som beskriver funktionerna i ditt API. Dokumentet baseras på XML och attributanteckningar i kontrollanterna och modellerna. Det är kärnan i OpenAPI-flödet och används för att köra verktyg som SwaggerUI. Som standard heter den openapi.json. Här är ett exempel på en OpenAPI-specifikation, reducerad för korthet:

{
  "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-användargränssnitt

Swagger UI erbjuder ett webbaserat användargränssnitt som tillhandahåller information om tjänsten med hjälp av den genererade OpenAPI-specifikationen. Både Swashbuckle och NSwag innehåller en inbäddad version av Swagger-användargränssnittet, så att det kan finnas i din ASP.NET Core-app med hjälp av ett registreringsanrop för mellanprogram. Webbgränssnittet ser ut så här:

Swagger-användargränssnitt

Varje publik åtgärdsmetod i dina kontroller kan testas från användargränssnittet. Välj ett metodnamn för att expandera avsnittet. Lägg till nödvändiga parametrar och välj Prova!.

Exempel på Swagger GET-test

Anmärkning

Swagger UI-versionen som används för skärmbilderna är version 2. Ett exempel på version 3 finns i Petstore-exempel.

Nästa steg