Dit bericht is voor het laatst bewerkt door QWERTYU op 12-4-2019 om 14:24
IntroductieNa het gebruik van asp.net Core voor API-ontwikkeling moet het schrijven van API-documentatie een lastige taak zijn voor programmeurs, maar de documentatie moet geschreven zijn, en als er geen specifieke eisen zijn voor het formaat van de documentatie, hangt de uiteindelijke documentatie volledig af van de stemming van de ontwikkelaar. Of wees gedetailleerder, of eenvoudiger. Is er dus een snelle en efficiënte manier om API-documentatie te bouwen? Het antwoord is ja, Swagger is een van de populairste documentatie-genererende tools voor REST API's!
Waarom Swagger gebruiken als een documentatietool voor REST API's- Swagger kan een interactieve API-console genereren waarmee ontwikkelaars snel API's kunnen leren en ermee experimenteren.
- Swagger kan client SDK-code genereren voor implementaties op verschillende platforms.
- Swaggerbestanden kunnen automatisch worden gegenereerd uit codecommentaren op veel verschillende platforms.
- Swagger heeft een sterke community met veel sterke bijdragers.
Hoe gebruik je Swagger om API-documentatie in asp.net core te genereren?- Swashbuckle.AspNetCore is een open-source project dat Swagger-documentatie genereert voor ASP.NET Core Web API.
- NSwag is een ander open-source project voor het integreren van Swagger UI of ReDoc in ASP.NET Core Web API's. Het biedt een manier om C#- en TypeScript-clientcode voor API's te genereren.
Het volgende is een voorbeeld van Swashbuckle.AspNetCoreWat zijn de componenten van een Swashbuckle?- Swashbuckle.AspNetCore.Swagger: Maakt het SwaggerDocument-object beschikbaar als een Swagger-objectmodel en middleware voor JSON-eindpunten.
- Swashbuckle.AspNetCore.SwaggerGen: Een Swagger-generator die SwaggerDocument-objecten direct genereert uit routes, controllers en modellen. Het wordt vaak gecombineerd met Swagger endpoint middleware om automatisch Swagger JSON te exposeren.
- Swashbuckle.AspNetCore.SwaggerUI: Een ingebedde versie van de Swagger UI-tool. Het interpreteert Swagger JSON om aanpasbare, rijke ervaringen te bouwen die de functionaliteit van web-API's beschrijven. Het bevat ingebouwde testtools voor veelvoorkomende methoden.
Hoe installeer je Swashbuckle met vs2017?
De eerste manier: installeren vanuit het Package Manager Console-venster
- Ga naar weergaven > andere Windows > Package Manager Console
- Navigeer naar de map die het TodoApi.csproj-bestand bevat
- Voer alstublieft het volgende commando uit · Install-Package Swashbuckle.AspNetCore
-
Tweede manier: Vanuit het dialoog 'NuGet pakketten beheren':- Klik met de rechtermuisknop op het project in Solution Explorer > Beheer NuGet-pakketten
- Stel de bron van het pakket in op nuget.org
- Typ "Swashbuckle.AspNetCore" in het zoekvak
- Selecteer het Swashbuckle.AspNetCore-pakket via het tabblad Bladeren en klik op Installeren
-
Voeg Swagger-middleware toe en configureerIntroduceer eerst de naamruimte: Voeg de Swagger-generator toe aan de servicecollectie in de Startup.ConfigureServices-methode: opStartup.ConfigureMethode, de middleware inschakelen om het gegenereerde JSON-document en de Swagger UI te bedienen:
Start de app en navigeer ernaartoe.https://localhost:<port>/swagger/v1/swagger.json。 De resulterende documentatie die het eindpunt beschrijft, wordt als volgt weergegeven in JSON-formaat.
Beschikbaarhttps://localhost:<port>/swaggerZoek de Swagger-gebruikersinterface. Bekijk de API-documentatie via de Swagger UI zoals hieronder weergegeven.
Om de stam toe te passen (http://localhost:<port>/) om de Swagger-UI te bieden, zet dan deRoutePrefixDe eigenschap wordt ingesteld op een lege string:
Geavanceerd gebruik van Swagger (Aanpassing en uitbreidingen)Gebruik Swagger om verklarende informatie toe te voegen aan de API-documentatieDe volgende configuratiebewerkingen worden uitgevoerd in de AddSwaggerGen-methode, die informatie toevoegt zoals auteur-, licentie- en beschrijvingsinformatie: De informatie van de Wagger UI-weergave wordt weergegeven in de volgende figuur: Voeg opmerkingen toe aan interface-methodenLaten we eerst op de API klikken, uitbreiden zoals te zien is in de onderstaande figuur, kunnen er geen reacties zijn, hoe voeg ik opmerkingen toe? Voeg documentopmerkingen toe met drie/zoals te zien is op de afbeelding hieronder, zoals hieronder te zien is Voer dan het project uit en ga terug naar de swaggerUI om te zien of de opmerking verschijnt Nog steeds niet verschenen, maak je geen zorgen, kijk naar beneden! Schakel XML-annotaties inJe kunt XML-annotaties inschakelen met de volgende methoden: - Klik met de rechtermuisknop op het project in Solution Explorer en selecteer Eigenschappen
- Kijk in het vakje XML Document File onder het Output-gedeelte van het tabblad Build.
-
Het inschakelen van XML-annotaties biedt debug-informatie voor ongedocumenteerde veelvoorkomende types en leden. Als er bijvoorbeeld veel waarschuwingsberichten verschijnen, duidt het volgende bericht op een overtreding van waarschuwingscode 1591:
Wat als je OCD hebt en de waarschuwing wilt annuleren? Je kunt annuleren zoals te zien is op de onderstaande afbeelding
Let op het pad van het hierboven gegenereerde xml-documentbestand,
Notitie: 1. Voor Linux- of niet-Windows-besturingssystemen zijn bestandsnamen en paden hoofdlettergevoelig. Bijvoorbeeld, een "SwaggerDemo.xml"-bestand werkt op Windows, maar niet op CentOS. 2. Om het applicatiepad te verkrijgen, wordt aanbevolen om AppContext.BaseDirectory te gebruiken om het te verkrijgen Bouw het project opnieuw op en start het om te zien of de reacties verschijnen Uit bovenstaande bewerking kan worden samengevat dat de Swagger UI de <summary> interne tekst van de elementen van bovenstaande commentaarcode als API-grote opmerkingen weergeeft! Natuurlijk kun je het element opmerkingen ook toevoegen aan de Handleiding-documentatie. Het kan <summary> de informatie in het element aanvullen en een betrouwbaardere Swagger-gebruikersinterface bieden. <remarks> Elementinhoud kan tekst, JSON of XML bevatten. De code is als volgt: Test de API-interface met SwaggerUILaten we de interface debuggen via SwaggerUI aan de hand van een klein voorbeeld
- Klik op een API-interface die getest moet worden, en klik vervolgens op de knop "Try it out" links en rechts van Parameters
- Voer een parameter in in het parametertekstvak dat verschijnt, zoals te zien is in de volgende afbeelding, en voer parameter 2 in
- Klik op de Execute-knop en het onderstaande opgemaakte antwoord verschijnt, zoals te zien is in de onderstaande figuur
Nou, dat was het voor de tutorial van vandaag over het gebruik van Swagger om API-documentatie te genereren in ASP.NET Core WebApi. Ik hoop dat het nuttig voor je is om te leren hoe je Swagger gebruikt om API-documentatie te genereren in ASP.NET Core! samenvattingDit artikel begint met het pijnpunt van het handmatig schrijven van API-documentatie en leidt vervolgens naar Swagger, een tool die automatisch API-documentatie genereert! Vervolgens zullen we aan de hand van gemakkelijk te begrijpen tekst en afbeeldingen demonstreren hoe je SwaggerUI gebruikt om API-documentatie te genereren in een ASP.NET Core WebApi. Tot slot zal ik enkele geavanceerde toepassingen van Swagger introduceren in ASP.NET Core! Ik hoop dat het je helpt om Swagger in ASP.NET Core te gebruiken!
| 
Geplaatst op 12-04-2019 14:14:46
|
|
|
|
