Ezt a bejegyzést utoljára a QWERTYU szerkesztette: 2019-4-12, 14:24
BevezetésMiután asp.net Core használata az API fejlesztéshez szükséges, az API dokumentáció megírása fájdalmas feladat lehet a programozók számára, de a dokumentációt meg kell írni, és ha nincs konkrét követelmény a dokumentáció formátumára, a végleges dokumentáció teljes mértékben a fejlesztő hangulatától függ. Vagy részletesebb, egyszerűbb legyen. Van tehát gyors és hatékony módja az API dokumentáció építésének? A válasz igen, a Swagger az egyik legnépszerűbb REST API dokumentáció generáló eszköz!
Miért használjuk a Swaggert REST API-k dokumentációs generáló eszközeként- A Swagger képes egy interaktív API konzolt generálni, amellyel a fejlesztők gyorsan tanulhatnak és kísérletezhetnek API-kkal.
- A Swagger képes ügyfél SDK kódot generálni különböző platformok megvalósításához.
- Swagger fájlok automatikusan generálhatók kódkommentekből sokféle platformon.
- A Swaggernek erős közössége van, sok erős közreműködővel.
Hogyan lehet a Swaggert használni API dokumentáció generálásához asp.net magban?- A Swashbuckle.AspNetCore egy nyílt forráskódú projekt, amely Swagger dokumentációt generál ASP.NET Core Web API-hoz.
- Az NSwag egy másik nyílt forráskódú projekt, amely a Swagger UI vagy ReDoc integrálására ASP.NET Core Web API-kba. Lehetőséget ad C# és TypeScript klienskód generálására API-khoz.
Az alábbiakban egy példa a Swashbuckle.AspNetCoreMik a Swashbuckle alkatrészei?- Swashbuckle.AspNetCore.Swagger: Expo a SwaggerDocument objektumot Swagger objektummodellként és middleware-ként JSON végpontokhoz.
- Swashbuckle.AspNetCore.SwaggerGen: Egy Swagger-generátor, amely közvetlenül útvonalakból, vezérlőkből és modellekből generál SwaggerDocument objektumokat. Gyakran kombinálják Swagger endpoint middleware-lel, hogy automatikusan elérhetővé tegye a Swagger JSON-t.
- Swashbuckle.AspNetCore.SwaggerUI: A Swagger UI eszköz beágyazott változata. A Swagger JSON-t úgy értelmezi, hogy testreszabható, gazdag élményeket hozzon létre, amelyek leírják a webes API-k funkcionalitását. Beépített teszteszközöket tartalmaz a gyakori módszerekhez.
Hogyan telepítsem a Swashbuckle-t a vs2017-re?
Az első mód: telepíts a Package Manager konzol ablakból
- Menj a Windows > Package Manager konzol> nézetekbe
- Navigáljon a TodoApi.csproj fájlt tartalmazó könyvtárhoz
- Kérem, hajtsa végre a következő parancsot · Install-Package Swashbuckle.AspNetCore
-
Második mód: A Manage NuGet Packages párbeszédből:- Jobb kattintással a projektre a Solution Explorerben > Manage NuGet csomagok
- Állítsd be a csomagforrást nuget.org
- Írd be a keresőmezőbe a "Swashbuckle.AspNetCore" kifejezést
- Válaszd ki a Swashbuckle.AspNetCore csomagot a Böngészés fülről, és kattints az Installációra
-
Hozzáadni és konfigurálni Swagger middleware-etElőször vezetd be a névteret: Hozzáadjuk a Swagger generátort a szolgáltatásgyűjteményhez a Startup.ConfigureServices metódusban: nélStartup.Configurea middleware-t engedélyezi a generált JSON dokumentum és a Swagger UI kiszolgálására:
Indítsd el az alkalmazást, és navigálj hozzáhttps://localhost:<port>/swagger/v1/swagger.json。 A végpontot leíró dokumentáció a JSON formátumban a következőképpen jelenik meg.
Elérhetőhttps://localhost:<port>/magabiztosságKeresd meg a Swagger UI-t. Böngéssze az API dokumentációját a Swagger UI-n keresztül, ahogy az alábbiakban látható.
A gyökér alkalmazásához (http://localhost:<port>/) a Swagger UI biztosításához kérjük, tegye aÚtvonalprefixA tulajdonság üres láncsorra van beállítva:
Swagger fejlett használata (testreszabás és kiterjesztések)Használd a Swaggert magyarázó információk hozzáadására az API dokumentációbaAz alábbi konfigurációs műveleteket az AddSwaggerGen módszerrel végzik, amely hozzáad olyan információkat, mint a szerző, licenc és leírás: A wagger UI kijelző verzió adatai az alábbi ábrán láthatók: Hozzászólások hozzáadása interfész módszerekhezElőször kattintsunk az API-ra, bővítsük ki, ahogy az alábbi ábrán látható, lehet, hogy nem lehet hozzászólás, hogyan lehet hozzászólásokat hozzáadni? Dokumentum hozzászólások három/ahogy az alábbi képen látható, ahogy az lent látható Ezután futtatom a projektet, és menj vissza a swaggerUI-hoz, hogy megnézd, megjelenik-e a hozzászólás Még mindig nem jelent meg, ne aggódj, nézz le! XML megjegyzések engedélyezéseAz alábbi módszerekkel engedélyezheted az XML annotációkat: - Kattintson a projektre a Megoldáskezelőben, és válassza ki a Tulajdonságokat
- Nézd meg az XML Dokumentumfájl dobozt a Build fül Kimenet szakaszában
-
Az XML annotációk engedélyezése hibátletó információkat nyújt dokumentálatlan gyakori típusok és tagok számára. Ha például sok figyelmeztető üzenet jelenik meg, a következő üzenet jelzi a 1591-es figyelmeztető kód megsértését:
Mi van, ha OCD-d van, és le akarod mondani a figyelmeztetést? Lemondhatod, ahogy az alábbi képen is látható
Figyeld meg a fent generált xml dokumentumfájl útvonalát,
Jegyzet: 1. Linux vagy nem Windows operációs rendszerek esetén a fájlnevek és útvonalak kis- és nagybetűk érzékenyek. Például egy "SwaggerDemo.xml" fájl működik Windowson, de a CentOS-on nem. 2. Az alkalmazás útjának megszerzéséhez ajánlott az AppContext.BaseDirectory segítségével megszerezni azt Építsd újra és indítsd el a projektet, hogy megnézd, megjelennek-e a hozzászólások A fenti műveletből összefoglalható, hogy a Swagger UI a <summary> fenti hozzászólás kódjának elemeinek belső szövegét API-s nagy hozzászólásként jeleníti meg! Természetesen a megjegyzéseket is hozzáadhatod a Getting how to dokumentációhoz. <summary> Kiegészítheti az elemben megadott információkat, és megbízhatóbb Swagger felhasználói felületet biztosít. <remarks> Az elemtartalom tartalmazhat szöveget, JSON-t vagy XML-t. A kódex a következő: Teszteld az api interfészt SwaggerUI-valA SwaggerUI-n keresztül egy kis példával debugozzuk a felületet
- Kattints egy tesztelendő API felületre, majd kattints a "Try it out" gombra a Paraméterek bal és jobb oldalán
- Írj be egy paramétert a paraméter szövegmezőbe, amely a következő képen látható, és írd be a 2-es paramétert
- Kattints az Execute gombra, és az alábbi formázott válasz megjelenik az alábbi ábrán látható
Nos, ennyi volt a mai oktatóanyag arról, hogyan lehet a Swagger segítségével API dokumentációt generálni ASP.NET Core WebApi-ban. Remélem, hasznos lesz megtanulni, hogyan kell használni a Swaggert API dokumentáció generálásához ASP.NET Core-ban! összefoglalásEz a cikk azzal kezdődik, hogy az API dokumentációt kézzel írjuk, majd a Swaggerhez vezet, amely automatikusan generál API dokumentációt! Ezután könnyen érthető szövegen és képeken keresztül bemutatjuk, hogyan lehet használni a SwaggerUI-t API dokumentáció generálásához egy ASP.NET Core WebApi-ban. Végül bemutatok néhány fejlett Swagger felhasználást ASP.NET Core-ban! Remélem, segít használni a Swaggert ASP.NET Core-ban!
| 
Közzétéve 2019. 04. 12. 14:14:46
|
|
|
|
