Ohjelmointirajapinnan dokumentointi Swashbucklen avulla

Valmis

Swashbuckle on NuGet-paketti, joka mahdollistaa Swagger-dokumentaation automaattisen luomisen WWW-ohjelmointirajapintaprojektien ASP.NET. Swagger on työkalu, jonka avulla kehittäjät voivat suunnitella, luoda, dokumentoida ja käyttää RESTful-ohjelmointirajapintoja. Swashbucklen avulla voit helposti lisätä Swagger-ohjeita WWW-ohjelmointirajapintaprojektiin lisäämällä koodiisi merkintöjä määritteisiin, jotka kuvaavat ohjelmointirajapinnan päätepisteitä, parametreja ja vastauksia. Swashbuckle luo näiden tietojen avulla Swagger JSON -tiedoston, jonka avulla voidaan luoda vuorovaikutteisia ohjelmointirajapintadokumentaatioita, asiakas-SDK:ita ja paljon muuta.

Swashbucklessa on kolme pääkomponenttia:

• Swashbuckle.AspNetCore.Swagger: Swagger-objektimalli ja väliohjelmisto, jotka paljastavat SwaggerDocument-objektit JSON-päätepisteinä.

• Swashbuckle.AspNetCore.SwaggerGen: Swagger-generaattori, joka rakentaa SwaggerDocument-objekteja suoraan reiteistäsi, ohjaimistasi ja malleistasi. Se yhdistetään yleensä Swagger-päätepisteen väliohjelmistoon, joka paljastaa Swagger JSON:n automaattisesti.

• Swashbuckle.AspNetCore.SwaggerUI: Swagger UI -työkalun upotettu versio. Swagger JSON tulkitsee sen avulla monipuolisen ja mukautettavan käyttökokemuksen verkon ohjelmointirajapinnan toiminnallisuuden kuvaamista varten. Se sisältää julkisten menetelmien sisäiset testivaljaat.

Seuraava dotnet add-komento asentaa Swashbuckle NuGet -paketin:

dotnet add <name>.csproj package Swashbuckle.AspNetCore -v 6.5.0

Swagger-väliohjelmiston lisääminen ja määrittäminen

Lisää Swagger-generaattori palvelukokoelmaan Program.cs.

builder.Services.AddEndpointsApiExplorer();
builder.Services.AddSwaggerGen();

Muistiinpano

Edellisessä esimerkissä näkyvä AddEndpointsApiExplorer kutsu vaaditaan vain pienimmillä ohjelmointirajapinnoilla.

Ota väliohjelmisto käyttöön luodun JSON-asiakirjan ja Swagger-käyttöliittymän palvelemiseksi myös Program.cs:

app.UseSwagger();
if (app.Environment.IsDevelopment())
{
    app.UseSwaggerUI();
}

Swagger-käyttöliittymän oletuspäätepiste on http:<hostname>:<port>/swagger.

Muistiinpano

SwaggerUI on erittäin hyödyllinen kehitysympäristössäsi. Se voidaan ottaa käyttöön tuotannossa, mutta ennen tätä on otettava huomioon oman sovelluksesi suojausvaatimukset.

Swagger-dokumentaation mukauttaminen ja laajentaminen

Swagger tarjoaa vaihtoehtoja objektimallin dokumentointiin ja käyttöliittymän mukauttamiseen. AddSwaggerGen -menetelmään välitetty määritystoiminto voi sisältää lisätietoja OpenApiInfo luokan kautta.

Seuraava koodiesimerkki näyttää, miten voit lisätä näytettäviä tietoja ohjelmointirajapinnan ohjeissa.

// Add using statement for the OpenApiInfo class
using Microsoft.OpenApi.Models;

builder.Services.AddSwaggerGen(options =>
{
    options.SwaggerDoc("v1", new OpenApiInfo
    {
        Version = "v1",
        Title = "Fruit API",
        Description = "API for managing a list of fruit their stock status.",
        TermsOfService = new Uri("https://example.com/terms")
    });
});

Swagger-käyttöliittymä näyttää version ja lisätyt tiedot:

Voit ryhmitellä ohjelmointirajapintasi toimintoja .WithTags-vaihtoehdon avulla. Voit myös lisätä kuvaavan tekstin, joka kuvaa toimintoa .WithSummary -asetuksen kanssa. Seuraavassa mallikoodissa näytetään POST.WithTags toiminnon ryhmittely sekä Post -ryhmään että fruit -ryhmään. Se myös lisää toimintoon .WithSummary -asetuksessa määritetyn yhteenvedon.

app.MapPost("/fruits", async (Fruit fruit, FruitDb db) =>
{
    db.Fruits.Add(fruit);
    await db.SaveChangesAsync();

    return Results.Created($"/{fruit.Id}", fruit);
})
    .Produces<Fruit>(201)
    .WithTags("post", "fruits")
    .WithSummary("Create a new fruit");

Swagger-käyttöliittymä näyttää määritetyn ryhmittelyn ja yhteenvedon kuvauksen.