C# Academy · leksjon

Generere OpenAPI-dokumenter

Produser maskinlesbare API-spesifikasjoner.

Leksjon 3 av 413 trinn

Generere OpenAPI-dokumenter er en gratis leksjon i C# Academy på CoddyKit. Dette er leksjon 3 av 4. Du kan lese hele leksjonen gratis nedenfor – og deretter øve praktisk i nettleseren med en innebygd kodeeditor og en AI-veileder som er tilgjengelig døgnet rundt. Den er en del av læringsløpet i C# Academy, og fremdriften din synkroniseres mellom nettet og CoddyKit-appen. Kurset i C# Academy inneholder totalt 4 leksjoner.

Hva er OpenAPI?

OpenAPI er en standardisert, maskinlesbar beskrivelse av et HTTP-API. Ut fra den kan De generere dokumentasjon, klient-SDK-er og verktøy for testing.

.NET 9 leveres med innebygd generering av OpenAPI-dokumenter, noe som erstatter den eldre Swashbuckle-avhengigheten i mange apper.

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

Pakken Microsoft.AspNetCore.OpenApi

Den innebygde støtten ligger i Microsoft.AspNetCore.OpenApi. I .NET 9-maler er den allerede referert til.

dotnet add package Microsoft.AspNetCore.OpenApi

AddOpenApi

Registrer dokumentgeneratoren med AddOpenApi i tjenestekonfigurasjonen.

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddOpenApi();

MapOpenApi

MapOpenApi eksponerer det genererte dokumentet på et endepunkt. Som standard leveres det på /openapi/v1.json.

var app = builder.Build();

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

app.Run();

Begrense til utviklingsmiljøet

Det er vanlig å eksponere dokumentet bare under utvikling, slik at De unngår å lekke API-flaten i produksjon.

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

Beskrive endepunkter

OpenAPI-metadata berikes ut fra koden. Bruk WithSummary, WithDescription og WithTags på minimal-API-endepunkter.

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

Dokumentere svar

Deklarer svartypene og statuskodene slik at dokumentet viser dem nøyaktig.

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

Dokumenttransformatorer

Tilpass hele dokumentet – tittel, versjon og servere – med en dokumenttransformator som 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;
    });
});

Operasjonstransformatorer

En operasjonstransformator justerer individuelle operasjoner – for eksempel ved å legge til en felles header-parameter for hvert endepunkt.

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

Legge til et brukergrensesnitt

Den innebygde generatoren produserer JSON-dokumentet, men ikke noe brukergrensesnitt. Kombiner den med en visning som Scalar eller Swagger UI.

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

Generere under bygging

De kan generere OpenAPI-filen under byggingen, uten en kjørende server, ved hjelp av verktøyene i Microsoft.Extensions.ApiDescription.Server. Dette er praktisk for generering av klienter i CI.

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

Rask kontroll

Bekreft det grunnleggende om OpenAPI i .NET 9.

Besvar den i den interaktive leksjonen

Oppsummering

De genererte OpenAPI-dokumenter:

AddOpenApi() registrerer generatoren, mens MapOpenApi() leverer JSON-en.
Berik endepunkter med WithSummary, Produces og tagger.
Dokument- og operasjonstransformatorer tilpasser resultatet.
Kombiner med Scalar eller Swagger UI for en interaktiv visning.

Neste trinn: dokumentere versjonerte API-er.

Gratis å komme i gang

Lær deg C# med en AI-veileder – gratis

Skriv og kjør ekte kode i nettleseren, få umiddelbar hjelp fra en AI-veileder som er tilgjengelig døgnet rundt, og fortsett der du slapp – på nettet eller i appen.

Kurs: 93
Leksjoner: 346

Start læringen gratis Se hele kurset

Ofte stilte spørsmål

Er leksjonen «Generere OpenAPI-dokumenter» gratis?

Ja – hele teksten i «Generere OpenAPI-dokumenter» er gratis å lese her på nettet. For å øve interaktivt med en innebygd kodeeditor og en AI-veileder som er tilgjengelig døgnet rundt, og for å låse opp resten av C# Academy-kurset, kan du oppgradere til CoddyKit PRO. Kurset i C# Academy inneholder totalt 4 leksjoner.

Hva lærer jeg i «Generere OpenAPI-dokumenter»?

Produser maskinlesbare API-spesifikasjoner. Du øver på C# Academy med praktisk kode som du kjører direkte i nettleseren, mens en AI-veileder som er tilgjengelig døgnet rundt, svarer på spørsmålene dine mens du jobber deg gjennom leksjonen.

Trenger jeg erfaring for å begynne med C# Academy?

Ingen tidligere erfaring er nødvendig. C# Academy på CoddyKit er lagt opp for både nybegynnere og viderekomne, så De kan begynne her eller helt fra start og lære i Deres eget tempo. Dette er leksjon 3 av 4.

Hvor lang tid tar leksjonen «Generere OpenAPI-dokumenter»?

De fleste CoddyKit-leksjoner tar omtrent 5–10 minutter. Hver leksjon er kort og interaktiv, slik at De gjør jevne fremskritt og kan fortsette akkurat der De slapp – både på nettet og i appen.

Kan jeg skrive og kjøre kode i denne C# Academy-leksjonen?

Ja. Alle C# Academy-leksjoner har en innebygd kodeeditor, slik at De kan skrive og kjøre ekte kode direkte i nettleseren og få umiddelbar tilbakemelding fra AI – uten lokal konfigurering.

Alle leksjonene i dette kurset

← Tilbake til C# Academy