C# Academy · Lektion

Generera OpenAPI-dokument

Skapa maskinläsbara API-specifikationer.

Lektion 3 av 413 steg

Generera OpenAPI-dokument är en gratis lektion i C# Academy på CoddyKit. Detta är lektion 3 av 4. Ni kan läsa hela lektionen gratis nedan och sedan öva praktiskt i webbläsaren med en inbyggd kodredigerare och en AI-handledare som är tillgänglig dygnet runt. Den ingår i lärvägen för C# Academy, och Era framsteg synkroniseras mellan webben och CoddyKit-appen. Kursen i C# Academy innehåller totalt 4 lektioner.

Vad är OpenAPI?

OpenAPI är en standardiserad, maskinläsbar beskrivning av ett HTTP-API. Utifrån den kan Du generera dokumentation, klient-SDK:er och verktyg för testning.

.NET 9 levereras med inbyggd generering av OpenAPI-dokument, vilket för många appar ersätter det äldre beroendet Swashbuckle.

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

Paketet Microsoft.AspNetCore.OpenApi

Det inbyggda stödet finns i Microsoft.AspNetCore.OpenApi. I .NET 9-mallarna finns paketet redan refererat.

dotnet add package Microsoft.AspNetCore.OpenApi

AddOpenApi

Registrera dokumentgeneratorn med AddOpenApi i tjänstekonfigurationen.

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddOpenApi();

MapOpenApi

MapOpenApi exponerar det genererade dokumentet via en endpoint. Som standard tillhandahålls det på /openapi/v1.json.

var app = builder.Build();

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

app.Run();

Begränsa till utvecklingsmiljön

Det är vanligt att endast exponera dokumentet i utvecklingsmiljön för att undvika att produktionsmiljöns API-yta läcker ut.

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

Beskriva endpoints

OpenAPI-metadata berikas utifrån Din kod. Använd WithSummary, WithDescription och WithTags på Minimal API-endpoints.

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

Dokumentera svar

Ange svarstyperna och statuskoderna så att dokumentet listar dem korrekt.

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

Dokumenttransformerare

Anpassa hela dokumentet – titel, version och servrar – med en dokumenttransformerare som skickas till AddOpenApi.

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

Operationstransformerare

En operationstransformerare justerar enskilda operationer – till exempel genom att lägga till en gemensam headerparameter för varje endpoint.

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

Lägga till ett användargränssnitt

Den inbyggda generatorn skapar JSON-dokumentet men inget användargränssnitt. Kombinera den med en visare som Scalar eller Swagger UI.

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

Generera vid byggtillfället

Du kan skapa OpenAPI-filen under bygget, utan en körande server, med verktygen i Microsoft.Extensions.ApiDescription.Server. Det är praktiskt för klientgenerering i CI.

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

Snabbkontroll

Bekräfta grunderna i OpenAPI i .NET 9.

Besvara frågan i den interaktiva lektionen

Sammanfattning

Du genererade OpenAPI-dokument:

AddOpenApi() registrerar generatorn; MapOpenApi() tillhandahåller JSON-dokumentet.
Berika endpoints med WithSummary, Produces och taggar.
Dokument- och operationstransformerare anpassar resultatet.
Kombinera med Scalar eller Swagger UI för en interaktiv vy.

Nästa steg: dokumentera versionshanterade API:er.

Gratis att börja

Lär dig C# med en AI-lärare – gratis

Skriv och kör riktig kod i webbläsaren, få omedelbar hjälp av en AI-lärare dygnet runt och fortsätt där du slutade – på webben eller i appen.

Kurser: 93
Lektioner: 346

Börja lära dig gratis Visa hela kursen

Vanliga frågor

Är lektionen ”Generera OpenAPI-dokument” gratis?

Ja – hela texten till ”Generera OpenAPI-dokument” kan läsas gratis här på webben. Om Ni vill öva interaktivt med en inbyggd kodredigerare och en AI-handledare som är tillgänglig dygnet runt och låsa upp resten av kursen i C# Academy, kan Ni uppgradera till CoddyKit PRO. Kursen i C# Academy innehåller totalt 4 lektioner.

Vad lär jag mig i ”Generera OpenAPI-dokument”?

Skapa maskinläsbara API-specifikationer. Ni övar på C# Academy med praktisk kod som körs direkt i webbläsaren, medan en AI-handledare som är tillgänglig dygnet runt svarar på Era frågor under lektionen.

Behöver jag någon erfarenhet för att börja lära mig C# Academy?

Du behöver inga förkunskaper. Utbildningen i C# Academy på CoddyKit är upplagd för allt från nybörjare till avancerade elever, så att du kan börja här eller från början och gå fram i din egen takt. Detta är lektion 3 av 4.

Hur lång tid tar lektionen ”Generera OpenAPI-dokument”?

De flesta CoddyKit-lektioner tar cirka 5–10 minuter. Varje lektion är kort och interaktiv, så att du gör stadiga framsteg och kan fortsätta precis där du slutade – på webben eller i appen.

Kan jag skriva och köra kod i den här C# Academy-lektionen?

Ja. Varje C# Academy-lektion innehåller en inbyggd kodredigerare, så att du kan skriva och köra riktig kod direkt i webbläsaren och få omedelbar AI-feedback – utan lokal installation.

Alla lektioner i den här kursen

← Tillbaka till C# Academy