C# Academy · Lektion

Generering af OpenAPI-dokumenter

Opret maskinlæsbare API-specifikationer.

Lektion 3 af 413 trin

Generering af OpenAPI-dokumenter er en gratis C# Academy-lektion på CoddyKit. Dette er lektion 3 af 4. Du kan læse hele lektionen gratis nedenfor — og derefter øve dig praktisk i browseren med en indbygget kodeeditor og en AI-vejleder, der er tilgængelig døgnet rundt. Den er en del af læringsforløbet i C# Academy, og dine fremskridt synkroniseres på tværs af nettet og CoddyKit-appen. C# Academy-kurset indeholder 4 lektioner i alt.

Hvad er OpenAPI?

OpenAPI er en standardiseret, maskinlæsbar beskrivelse af et HTTP-API. Ud fra den kan du generere dokumentation, klient-SDK'er og værktøjer til test.

.NET 9 leveres med indbygget generering af OpenAPI-dokumenter, som i mange apps erstatter den ældre Swashbuckle-afhængighed.

// OpenAPI document = JSON describing paths, schemas, params

Pakken Microsoft.AspNetCore.OpenApi

Den indbyggede understøttelse findes i Microsoft.AspNetCore.OpenApi. I .NET 9-skabeloner er pakken allerede refereret.

dotnet add package Microsoft.AspNetCore.OpenApi

AddOpenApi

Registrér dokumentgeneratoren med AddOpenApi i din tjenestekonfiguration.

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddOpenApi();

MapOpenApi

MapOpenApi eksponerer det genererede dokument på et slutpunkt. Som standard leveres det på /openapi/v1.json.

var app = builder.Build();

app.MapOpenApi();   // GET /openapi/v1.json

app.Run();

Begrænsning til udvikling

Det er almindeligt kun at eksponere dokumentet under udvikling for at undgå at afsløre din API-overflade i produktionen.

if (app.Environment.IsDevelopment())
{
    app.MapOpenApi();
}

Beskrivelse af slutpunkter

OpenAPI-metadata beriges ud fra din kode. Brug WithSummary, WithDescription og WithTags på slutpunkter i minimale API'er.

app.MapGet("/products/{id}", (int id) => Results.Ok())
   .WithSummary("Get a product by id")
   .WithDescription("Returns a single product or 404.")
   .WithTags("Products");

Dokumentation af svar

Deklarér svartypen og statuskoderne, så dokumentet viser dem korrekt.

app.MapGet("/products/{id}", (int id) => Results.Ok())
   .Produces<Product>(StatusCodes.Status200OK)
   .Produces(StatusCodes.Status404NotFound);

Dokumenttransformere

Tilpas hele dokumentet – titel, version og servere – med en dokumenttransformer, der sendes til AddOpenApi.

builder.Services.AddOpenApi(options =>
{
    options.AddDocumentTransformer((doc, ctx, ct) =>
    {
        doc.Info.Title = "Catalog API";
        doc.Info.Version = "1.0";
        return Task.CompletedTask;
    });
});

Operationstransformere

En operationstransformer justerer individuelle operationer – for eksempel ved at tilføje en fælles headerparameter til hvert slutpunkt.

options.AddOperationTransformer((operation, ctx, ct) =>
{
    operation.Responses.TryAdd("500",
        new OpenApiResponse { Description = "Server error" });
    return Task.CompletedTask;
});

Tilføjelse af en brugergrænseflade

Den indbyggede generator producerer JSON-dokumentet, men ingen brugergrænseflade. Kombinér den med et visningsværktøj som Scalar eller Swagger UI.

// dotnet add package Scalar.AspNetCore
app.MapOpenApi();
app.MapScalarApiReference();  // interactive docs at /scalar/v1

Generering under byggeprocessen

Du kan generere OpenAPI-filen under byggeprocessen (uden en kørende server) ved hjælp af værktøjerne i Microsoft.Extensions.ApiDescription.Server, hvilket er praktisk til generering af klienter i CI.

// .csproj
// <OpenApiGenerateDocuments>true</OpenApiGenerateDocuments>
// produces obj/<App>.json on build

Hurtigt tjek

Bekræft det grundlæggende om OpenAPI i .NET 9.

Besvar den i den interaktive lektion

Opsummering

Du genererede OpenAPI-dokumenter:

AddOpenApi() registrerer generatoren, og MapOpenApi() leverer JSON-dokumentet.
Berig slutpunkter med WithSummary, Produces og tags.
Dokument- og operationstransformere tilpasser resultatet.
Kombinér med Scalar eller Swagger UI for at få en interaktiv visning.

Næste emne: dokumentation af versionerede API'er.

Gratis at komme i gang

Lær C# med en AI-underviser — gratis

Skriv og kør rigtig kode i din browser, få øjeblikkelig hjælp fra en AI-underviser døgnet rundt, og fortsæt, hvor du slap, på web eller i appen.

Kurser: 93
Lektioner: 346

Start gratis Se hele kurset

Ofte stillede spørgsmål

Er lektionen “Generering af OpenAPI-dokumenter” gratis?

Ja — hele teksten til “Generering af OpenAPI-dokumenter” kan læses gratis her på nettet. Hvis du vil øve dig interaktivt med en indbygget kodeeditor og en AI-vejleder døgnet rundt og få adgang til resten af C# Academy-kurset, skal du opgradere til CoddyKit PRO. C# Academy-kurset indeholder 4 lektioner i alt.

Hvad lærer jeg i “Generering af OpenAPI-dokumenter”?

Opret maskinlæsbare API-specifikationer. Du øver dig i C# Academy med praktisk kode, som du kører direkte i browseren, og en AI-vejleder døgnet rundt besvarer dine spørgsmål, mens du arbejder dig gennem lektionen.

Skal jeg have erfaring for at begynde på C# Academy?

Der kræves ingen tidligere erfaring. C# Academy på CoddyKit er tilrettelagt for både begyndere og øvede, så du kan starte her eller fra begyndelsen og lære i dit eget tempo. Dette er lektion 3 af 4.

Hvor lang tid tager lektionen “Generering af OpenAPI-dokumenter”?

De fleste CoddyKit-lektioner tager cirka 5–10 minutter. Hver lektion er kort og interaktiv, så du gør løbende fremskridt og kan fortsætte, hvor du slap – på både web og app.

Kan jeg skrive og køre kode i denne C# Academy-lektion?

Ja. Alle C# Academy-lektioner har en indbygget kodeeditor, så du kan skrive og køre rigtig kode direkte i din browser og få øjeblikkelig feedback fra AI – uden lokal opsætning.

Alle lektioner i dette kursus

← Tilbage til C# Academy