Dažnai norėsite sukurti savo API dokumentaciją. Norėdami sukurti šią dokumentaciją, galite pasinaudoti „Swagger“ pranašumais - įrankiu, kuris gali būti naudojamas lengvai pateikiant jūsų API vartotojo sąsają. Kai sukursite „Swagger“ dokumentaciją savo API, galėsite peržiūrėti savo API metodų parašą ir net išbandyti savo API metodus.
„Swashbuckle“ yra atviro kodo „Swagger“ dokumentų generavimo projektas. Šiame straipsnyje aptariama, kaip mes galime pasinaudoti „Swashbuckle“ pranašumais, kad generuotume interaktyvią dokumentaciją mūsų RESTful API.
Sukurkite „ASP.Net Core“ projektą
Pirmiausia sukurkime ASP.Net Core projektą „Visual Studio“. Darant prielaidą, kad „Visual Studio 2017“ arba „Visual Studio 2019“ yra įdiegta jūsų sistemoje, atlikite toliau nurodytus veiksmus, kad sukurtumėte naują „ASP.Net Core“ projektą „Visual Studio“.
- Paleiskite „Visual Studio IDE“.
- Spustelėkite „Sukurti naują projektą“.
- Lange „Kurti naują projektą“ iš rodomų šablonų sąrašo pasirinkite „ASP.Net Core Web Application“.
- Spustelėkite Pirmyn.
- Lange „Konfigūruoti naują projektą“, kuris rodomas toliau, nurodykite naujo projekto pavadinimą ir vietą.
- Spustelėkite Sukurti.
- Lange „Kurti naują ASP.Net pagrindinę žiniatinklio programą“ viršuje esančiame išskleidžiamajame sąraše pasirinkite .Net Core kaip vykdymo laiką ir ASP.Net Core 2.2 (ar naujesnę).
- Pasirinkite „API“ kaip projekto šabloną, kad sukurtumėte naują ASP.Net Core Web API projektą.
- Įsitikinkite, kad nepažymėti žymės langeliai „Įgalinti„ Docker “palaikymą“ ir „Konfigūruoti HTTPS“, nes čia nenaudosime tų funkcijų.
- Įsitikinkite, kad autentifikavimas nustatytas kaip „Be autentifikavimo“, nes mes taip pat nenaudosime autentifikavimo.
- Spustelėkite Sukurti.
Atlikę šiuos veiksmus, „Visual Studio“ sukursite naują ASP.Net Core projektą. Šį projektą naudosime tolesniuose šio straipsnio skyriuose, kad ištirtume, kaip mes galime sugeneruoti „Swagger“ dokumentus „ValuesController“.
Įdiekite „Swagger“ tarpinę programinę įrangą į ASP.Net Core
Jei sėkmingai sukūrėte ASP.Net Core projektą, kitas dalykas, kurį turėtumėte padaryti, yra pridėti reikiamus „NuGet“ paketus prie savo projekto. Norėdami tai padaryti, lange Solution Explorer pasirinkite projektą, dešiniuoju pelės mygtuku spustelėkite ir pasirinkite „Manage NuGet Packages ....“ Lange „NuGet Package Manager“ ieškokite paketo „Swashbuckle.AspNetCore“ ir įdiekite jį. Arba galite įdiegti paketą per „NuGet Package Manager Console“, kaip parodyta žemiau.
PM> „Install-Package Swashbuckle.AspNetCore“
Pakete „Swashbuckle.AspNetCore“ yra reikalingi įrankiai, skirti kurti ASP.Net Core API dokumentus.
Konfigūruokite „Swagger“ tarpinę programinę įrangą ASP.Net Core
Norėdami sukonfigūruoti „Swagger“, „ConfigureServices“ metodu įrašykite šį kodą. Atkreipkite dėmesį, kaip „AddSwaggerGen“ plėtinio metodas naudojamas nurodant API dokumento metaduomenis.
paslaugos.AddSwaggerGen (c =>{
c.SwaggerDoc ("v1", nauja informacija
{
Versija = "v1",
Pavadinimas = „Swagger Demo“,
Aprašymas = "Swagger Demo for ValuesController",
TermsOfService = "Nėra",
Kontaktas = naujas kontaktas () {Name = "Joydip Kanjilal",
Paštas = "[email protected]",
URL = "www.google.com"}
});
});
Taip pat turėtumėte įgalinti „Swagger“ vartotojo sąsają naudodami konfigūravimo metodą, kaip parodyta žemiau.
app.UseSwagger ();app.UseSwaggerUI (c =>
{
c.SwaggerEndpoint ("/ swagger / v1 / swagger.json", "v1");
});
Čia yra visas jūsų „Startup“ klasės kodas.
naudojant „Microsoft.AspNetCore.Builder“;naudojant „Microsoft.AspNetCore.Hosting“;
naudojant „Microsoft.AspNetCore.Mvc“;
naudojant „Microsoft.Extensions.Configuration“;
naudojant „Microsoft.Extensions.DependencyInjection“;
naudojant „Swashbuckle.AspNetCore.Swagger“;
vardų sritis „SwaggerDemo“
{
viešosios klasės „Startup“
{
viešasis paleidimas (ICkonfigūracijos konfigūracija)
{
Konfigūracija = konfigūracija;
}
viešoji ICkonfigūracijos konfigūracija {get; }
public void „ConfigureServices“ („IServiceCollection“ paslaugos)
{
paslaugos. „AddMvc“ (). „SetCompatibilityVersion“
(CompatibilityVersion.Version_2_2);
paslaugos.AddSwaggerGen (c =>
{
c.SwaggerDoc ("v1", nauja informacija
{
Versija = "v1",
Pavadinimas = „Swagger Demo“,
Aprašymas = "Swagger Demo for ValuesController",
TermsOfService = "Nėra",
Kontaktas = naujas kontaktas () {Name = "Joydip Kanjilal",
Paštas = "[email protected]",
URL = "www.google.com"
}
});
});
}
public void Konfigūruoti („IApplicationBuilder“ programa,
IHostingEnvironment env)
{
jei (env.IsDevelopment ())
{
app.UseDeveloperExceptionPage ();
}
app.UseMvc ();
app.UseSwagger ();
app.UseSwaggerUI (c =>
{
c.SwaggerEndpoint ("/ swagger / v1 / swagger.json", "v1");
});
}
}
}
Tai viskas, ką jums reikia padaryti, norint pradėti naudotis „Swagger“.
Naršykite savo „ASP.Net Core“ programos „Swagger“ vartotojo sąsają
Dabar mes pasirengę vykdyti programą ir naršyti „Swagger“ galinį tašką. „Swagger“ vartotojo sąsaja pasirodys taip, kaip pavaizduota 1 paveiksle. Atkreipkite dėmesį, kaip „Swagger“ naudoja skirtingas spalvas HTTP veiksmažodžiams GET, PUT, POST ir DELETE. Kiekvieną iš 1 paveiksle nurodytų galinių taškų galite vykdyti tiesiai iš „Swagger“ vartotojo sąsajos.
Kurkite XML komentarus valdiklio veiksmų metoduose
Kol kas viskas gerai. Anksčiau sugeneruotame „Swagger“ dokumente XML komentarų nebuvo. Jei norite parodyti XML komentarus „Swagger“ dokumente, paprasčiausiai parašykite tuos komentarus valdiklio veiksmų metoduose.
Parašykime kiekvieno „ValuesController“ veiksmo metodo komentarus. Čia yra atnaujinta „ValuesController“ versija su XML komentarais kiekvienam veiksmo metodui.
[Maršrutas („api / [valdiklis]“)][ApiController]
viešosios klasės „ValuesController“: „ControllerBase“
{
///
/// Gaukite veiksmo metodą be jokių argumentų
///
///
[HttpGet]
viešas „ActionResult“
Gauti () {
grąžinti naują eilutę [] {"value1", "value2"};
}
///
/// Gauti veiksmo metodą, kuris priima sveikąjį skaičių kaip argumentą
///
///
///
[„HttpGet“ („{id}“)]
public ActionResult Get (int id)
{
grąžinti „vertė“;
}
///
/// Paskelbkite veiksmo metodą, kad pridėtumėte duomenis
///
///
[HttpPost]
public void Skelbimas ([FromBody] eilutės vertė)
{
}
///
/// Įdėkite veiksmo metodą duomenims modifikuoti
///
///
///
[„HttpPut“ („{id}“)]
public void „Put“ (int id, [FromBody] eilutės vertė)
{
}
///
/// Ištrinti veiksmo metodą
///
///
[„HttpDelete“ („{id}“)]
public void Ištrinti (int id)
{
}
}
„Swagger“ įjunkite XML komentarus
Atminkite, kad „Swagger“ pagal numatytuosius nustatymus nerodo XML komentarų. Turite įjungti šią funkciją. Norėdami tai padaryti, dešiniuoju pelės mygtuku spustelėkite Projektas, pasirinkite Ypatybės ir eikite į skirtuką Sukurti. Skirtuke „Sukurti“ pažymėkite parinktį „XML dokumentacijos failas“, kad nurodytumėte vietą, kur bus sukurtas XML dokumentacijos failas.
Taip pat turėtumėte nurodyti, kad XML komentarai turėtų būti įtraukti kuriant „Swagger“ dokumentą, metodą „ConfigureServices“ įrašant šį kodą.
c.IncludeXmlComments (@ "D: \ Projects \ SwaggerDemo \ SwaggerDemo \ SwaggerDemo.xml");
Ir tai viskas, ką jums reikia padaryti, kad „Swagger“ įjungtumėte XML komentarus.
Nustatykite programos paleidimo URL į „Swagger“ vartotojo sąsają
Galite pakeisti savo programos paleidimo URL, kad nurodytumėte, jog „Swagger“ vartotojo sąsaja bus įkelta paleidus programą. Norėdami tai padaryti, dešiniuoju pelės mygtuku spustelėkite Projektas ir pasirinkite Ypatybės. Tada eikite į skirtuką Derinti. Galiausiai nurodykite „Launch Browser“ vertę kaip pasikeitusią, kaip parodyta 2 paveiksle.
Kai dar kartą paleidžiate programą ir einate į „Swagger“ URL, turėtumėte pamatyti „Swagger“ vartotojo sąsają, kaip parodyta 3 paveiksle. Šį kartą atkreipkite dėmesį į XML komentarus kiekviename iš API metodų.
„Swashbuckle“ yra puikus įrankis generuojant „Swagger“ dokumentus jūsų API. Svarbiausia, kad „Swashbuckle“ būtų lengva konfigūruoti ir naudoti. Su „Swagger“ galite padaryti daug daugiau, nei mes matėme čia. Galite pritaikyti „Swagger“ vartotojo sąsają naudodami „Kaskadinio stiliaus lenteles“, rodyti „enum“ reikšmes kaip eilutės reikšmes ir sukurti skirtingus „Swagger“ dokumentus skirtingoms API versijoms, kad tik keli būtų išvardyti.
