C# Academy · Oppitunti

OpenAPI-dokumenttien luonti

Tuottakaa koneellisesti luettavia API-kuvauksia.

Oppitunti 3/413 vaihetta

OpenAPI-dokumenttien luonti on ilmainen C# Academy-oppitunti CoddyKitissä. Tämä on oppitunti 3/4. Voit lukea koko oppitunnin alta ilmaiseksi ja harjoitella sen jälkeen käytännössä selaimessa sisäänrakennetulla koodieditorilla ja ympäri vuorokauden käytettävissä olevan tekoälytuutorin avulla. Oppitunti kuuluu C# Academy-oppimispolkuun, ja edistymisesi synkronoituu verkon ja CoddyKit-sovelluksen välillä. C# Academy-kurssilla on yhteensä 4 oppituntia.

Mikä OpenAPI on

OpenAPI on HTTP-rajapinnan standardoitu, koneellisesti luettava kuvaus. Sen avulla voidaan luoda dokumentaatiota, asiakas-SDK:ita ja testaustyökaluja.

.NET 9 sisältää OpenAPI-dokumenttien luonnin sisäänrakennettuna, joten monissa sovelluksissa se korvaa vanhemman Swashbuckle-riippuvuuden.

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

Microsoft.AspNetCore.OpenApi-paketti

Sisäänrakennettu tuki sisältyy pakettiin Microsoft.AspNetCore.OpenApi. .NET 9 -mallipohjissa siihen on jo viittaus.

dotnet add package Microsoft.AspNetCore.OpenApi

AddOpenApi

Rekisteröi dokumenttien luonti palvelukokoonpanossa komennolla AddOpenApi.

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddOpenApi();

MapOpenApi

MapOpenApi julkaisee luodun dokumentin päätepisteessä. Oletusarvoisesti se palvelee dokumenttia osoitteessa /openapi/v1.json.

var app = builder.Build();

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

app.Run();

Rajoittaminen kehitysympäristöön

Dokumentti julkaistaan usein vain kehitysympäristössä, jotta rajapinnan laajuus ei paljastu tuotannossa.

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

Päätepisteiden kuvaaminen

OpenAPI-metatietoja täydennetään koodisi perusteella. Käytä Minimal API -päätepisteissä metodeja WithSummary, WithDescription ja WithTags.

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

Vastausten dokumentointi

Ilmoita vastaustyypit ja tilakoodit, jotta dokumentti luettelee ne täsmällisesti.

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

Dokumenttimuuntimet

Muokkaa koko dokumenttia – esimerkiksi otsikkoa, versiota ja palvelimia – välittämällä dokumenttimuunnin komennolle AddOpenApi.

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

Operaatiomuuntimet

Operaatiomuunnin muokkaa yksittäisiä operaatioita, esimerkiksi lisäämällä yhteisen otsakeparametrin jokaiseen päätepisteeseen.

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

Käyttöliittymän lisääminen

Sisäänrakennettu luonnin toiminnot tuottavat JSON-dokumentin, mutta eivät käyttöliittymää. Yhdistä ne katselimeen, kuten Scalariin tai Swagger UI:hin.

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

Luominen käännöksen aikana

OpenAPI-tiedoston voi tuottaa käännöksen aikana ilman käynnissä olevaa palvelinta Microsoft.Extensions.ApiDescription.Server -työkaluilla. Tämä on kätevää esimerkiksi CI-ympäristössä asiakasohjelmien luontia varten.

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

Pikatarkistus

Varmista .NET 9:n OpenAPI-perusteet.

Vastaa interaktiivisessa oppitunnissa

Kertaus

Loit OpenAPI-dokumentteja:

AddOpenApi() rekisteröi luonnin ja MapOpenApi() palvelee JSON-dokumenttia.
Täydennä päätepisteitä metodeilla WithSummary, Produces ja tunnisteilla.
Dokumentti- ja operaatiomuuntimet mukauttavat tulostetta.
Yhdistä kokonaisuus Scalarin tai Swagger UI:n kanssa interaktiivista näkymää varten.

Seuraavaksi: versioitujen rajapintojen dokumentointi.

Aloita maksutta

Opi C# tekoälytuutorin avulla — ilmaiseksi

Kirjoita ja suorita oikeaa koodia selaimessa, saa välitöntä apua tekoälytuutorilta ympäri vuorokauden ja jatka siitä, mihin jäit, verkossa tai sovelluksessa.

Kurssit: 93
Oppitunnit: 346

Aloita opiskelu maksutta Näytä koko kurssi

Usein kysytyt kysymykset

Onko oppitunti ”OpenAPI-dokumenttien luonti” ilmainen?

Kyllä – oppitunnin ”OpenAPI-dokumenttien luonti” koko tekstin voi lukea täällä verkossa ilmaiseksi. Jos haluat harjoitella interaktiivisesti sisäänrakennetulla koodieditorilla ja ympäri vuorokauden käytettävissä olevan tekoälytuutorin avulla sekä avata koko C# Academy-kurssin, päivitä CoddyKit PROhon. C# Academy-kurssilla on yhteensä 4 oppituntia.

Mitä opin oppitunnilla ”OpenAPI-dokumenttien luonti”?

Tuottakaa koneellisesti luettavia API-kuvauksia. Harjoittelet C# Academy-aihetta koodilla, jonka suoritat suoraan selaimessa. Ympäri vuorokauden käytettävissä oleva tekoälytuutori vastaa kysymyksiisi oppitunnin aikana.

Tarvitsenko kokemusta aloittaakseni C# Academy-opiskelun?

Aiempi kokemus ei ole tarpeen. CoddyKitin C# Academy-oppimispolku sopii vasta-alkajista edistyneisiin, joten voit aloittaa tästä tai alusta ja edetä omaan tahtiisi. Tämä on oppitunti 3/4.

Kuinka kauan ”OpenAPI-dokumenttien luonti”-oppitunnin suorittaminen kestää?

Useimmat CoddyKitin oppitunnit kestävät noin 5–10 minuuttia. Jokainen oppitunti on lyhyt ja interaktiivinen, joten edistyt tasaisesti ja voit jatkaa siitä, mihin jäit – sekä verkossa että sovelluksessa.

Voinko kirjoittaa ja suorittaa koodia tällä C# Academy-oppitunnilla?

Kyllä. Jokainen C# Academy-oppitunti sisältää sisäänrakennetun koodieditorin, joten voit kirjoittaa ja suorittaa oikeaa koodia suoraan selaimessa ja saada välitöntä palautetta tekoälyltä – paikallista asennusta ei tarvita.

Kaikki tämän kurssin oppitunnit

API-versiointistrategiat
Asp.Versioningin määrittäminen
OpenAPI-dokumenttien luonti
Versioitujen API-rajapintojen dokumentointi

← Takaisin: C# Academy