Συχνά θέλετε να δημιουργήσετε τεκμηρίωση για το API σας. Για να δημιουργήσετε αυτήν την τεκμηρίωση, μπορείτε να εκμεταλλευτείτε το Swagger - ένα εργαλείο που μπορεί να χρησιμοποιηθεί για να παρέχει ευκολία την αναπαράσταση διεπαφής χρήστη του API σας. Μόλις δημιουργήσετε τεκμηρίωση Swagger για το API σας, μπορείτε να δείτε την υπογραφή των μεθόδων API σας και ακόμη και να δοκιμάσετε τις μεθόδους API σας.
Το Swashbuckle είναι ένα έργο ανοιχτού κώδικα για τη δημιουργία εγγράφων Swagger. Αυτό το άρθρο παρουσιάζει μια συζήτηση για το πώς μπορούμε να εκμεταλλευτούμε το Swashbuckle για να δημιουργήσουμε διαδραστική τεκμηρίωση για το RESTful API μας.
Δημιουργήστε ένα έργο ASP.Net Core
Πρώτα απ 'όλα, ας δημιουργήσουμε ένα έργο ASP.Net Core στο Visual Studio. Υποθέτοντας ότι το Visual Studio 2017 ή το Visual Studio 2019 είναι εγκατεστημένο στο σύστημά σας, ακολουθήστε τα βήματα που περιγράφονται παρακάτω για να δημιουργήσετε ένα νέο έργο ASP.Net Core στο Visual Studio.
- Εκκινήστε το Visual Studio IDE.
- Κάντε κλικ στο "Δημιουργία νέου έργου".
- Στο παράθυρο "Δημιουργία νέου έργου", επιλέξτε "ASP.Net Core Web Application" από τη λίστα των προτύπων που εμφανίζονται.
- Κάντε κλικ στο Επόμενο.
- Στο παράθυρο "Διαμόρφωση του νέου έργου" που εμφανίζεται στη συνέχεια, καθορίστε το όνομα και την τοποθεσία για το νέο έργο.
- Κάντε κλικ στο Δημιουργία.
- Στο παράθυρο "Δημιουργία νέας εφαρμογής ASP.Net Core Web", επιλέξτε .Net Core ως χρόνο εκτέλεσης και ASP.Net Core 2.2 (ή μεταγενέστερη έκδοση) από την αναπτυσσόμενη λίστα στην κορυφή.
- Επιλέξτε "API" ως πρότυπο έργου για να δημιουργήσετε ένα νέο έργο ASP.Net Core Web API.
- Βεβαιωθείτε ότι τα πλαίσια ελέγχου "Ενεργοποίηση υποστήριξης Docker" και "Διαμόρφωση για HTTPS" δεν είναι επιλεγμένα, καθώς δεν θα χρησιμοποιούμε αυτές τις δυνατότητες εδώ.
- Βεβαιωθείτε ότι ο Έλεγχος ταυτότητας έχει οριστεί ως "Χωρίς έλεγχο ταυτότητας", καθώς ούτε θα χρησιμοποιούμε έλεγχο ταυτότητας.
- Κάντε κλικ στο Δημιουργία.
Ακολουθώντας αυτά τα βήματα θα δημιουργήσετε ένα νέο έργο ASP.Net Core στο Visual Studio. Θα χρησιμοποιήσουμε αυτό το έργο στις επόμενες ενότητες αυτού του άρθρου για να εξετάσουμε πώς μπορούμε να δημιουργήσουμε τεκμηρίωση Swagger για το ValueController.
Εγκαταστήστε το Swagger middleware στο ASP.Net Core
Εάν έχετε δημιουργήσει με επιτυχία ένα έργο ASP.Net Core, το επόμενο πράγμα που πρέπει να κάνετε είναι να προσθέσετε τα απαραίτητα πακέτα NuGet στο έργο σας. Για να το κάνετε αυτό, επιλέξτε το έργο στο παράθυρο Solution Explorer, κάντε δεξί κλικ και επιλέξτε "Διαχείριση πακέτων NuGet ...." Στο παράθυρο του Διαχειριστή πακέτων NuGet, αναζητήστε το πακέτο Swashbuckle.AspNetCore και εγκαταστήστε το. Εναλλακτικά, μπορείτε να εγκαταστήσετε το πακέτο μέσω του NuGet Package Manager Console όπως φαίνεται παρακάτω.
PM> Εγκατάσταση-πακέτο Swashbuckle.AspNetCore
Το πακέτο Swashbuckle.AspNetCore περιέχει τα απαραίτητα εργαλεία για τη δημιουργία εγγράφων API για ASP.Net Core.
Ρύθμιση παραμέτρων Swagger middleware στο ASP.Net Core
Για να ρυθμίσετε το Swagger, γράψτε τον ακόλουθο κώδικα στη μέθοδο ConfigureServices. Σημειώστε πώς χρησιμοποιείται η μέθοδος επέκτασης AddSwaggerGen για τον καθορισμό των μεταδεδομένων για το έγγραφο API.
υπηρεσίες.AddSwaggerGen (c =>{
c.SwaggerDoc ("v1", νέες πληροφορίες
{
Έκδοση = "v1",
Τίτλος = "Swagger Demo",
Περιγραφή = "Swagger Demo for ValuesController",
ΌροιOfService = "Κανένα",
Επικοινωνία = νέα επαφή () {Όνομα = "Joydip Kanjilal",
Email = "[email protected]",
Url = "www.google.com"}
});
});
Θα πρέπει επίσης να ενεργοποιήσετε το Swagger UI στη μέθοδο Configure όπως φαίνεται παρακάτω.
app.UseSwagger ();app.UseSwaggerUI (c =>
{
c.SwaggerEndpoint ("/ swagger / v1 / swagger.json", "v1");
});
Εδώ είναι ο πλήρης κωδικός της τάξης εκκίνησης για αναφορά σας.
χρησιμοποιώντας το Microsoft.AspNetCore.Builder;χρησιμοποιώντας το Microsoft.AspNetCore.Hosting;
χρησιμοποιώντας Microsoft.AspNetCore.Mvc;
χρησιμοποιώντας το Microsoft.Extensions.Configuration;
χρησιμοποιώντας το Microsoft.Extensions.DependencyInjection;
χρησιμοποιώντας Swashbuckle.AspNetCore.Swagger;
namespace SwaggerDemo
{
εκκίνηση δημόσιας τάξης
{
δημόσια εκκίνηση (διαμόρφωση IC Configuration)
{
Διαμόρφωση = διαμόρφωση;
}
δημόσια διαμόρφωση IConfiguration {get; }
public void ConfigureServices (υπηρεσίες IServiceCollection)
{
services.AddMvc (). SetCompatibilityVersion
(CompatibilityVersion.Version_2_2);
υπηρεσίες.AddSwaggerGen (c =>
{
c.SwaggerDoc ("v1", νέες πληροφορίες
{
Έκδοση = "v1",
Τίτλος = "Swagger Demo",
Περιγραφή = "Swagger Demo for ValuesController",
ΌροιOfService = "Κανένας",
Επικοινωνία = νέα επαφή () {Όνομα = "Joydip Kanjilal",
Email = "[email protected]",
Url = "www.google.com"
}
});
});
}
public void Configure (εφαρμογή IApplicationBuilder,
IHostingEnvironment env)
{
εάν (env.IsDevelopment ())
{
app.UseDeveloperExceptionPage ();
}
app.UseMvc ();
app.UseSwagger ();
app.UseSwaggerUI (c =>
{
c.SwaggerEndpoint ("/ swagger / v1 / swagger.json", "v1");
});
}
}
}
Αυτό είναι το μόνο που πρέπει να κάνετε για να ξεκινήσετε με το Swagger.
Περιηγηθείτε στο Swagger UI της εφαρμογής ASP.Net Core
Τώρα είμαστε έτοιμοι να εκτελέσουμε την εφαρμογή και να περιηγηθούμε στο τελικό σημείο του Swagger. Το Swagger UI θα εμφανιστεί όπως στο Σχήμα 1 παρακάτω. Σημειώστε πώς ο Swagger χρησιμοποιεί διαφορετικά χρώματα για τα ρήματα HTTP GET, PUT, POST και DELETE. Μπορείτε να εκτελέσετε καθένα από τα τελικά σημεία που φαίνονται στο Σχήμα 1 απευθείας από το Swagger UI.
Δημιουργήστε σχόλια XML στις μεθόδους δράσης του ελεγκτή σας
Μέχρι εδώ καλά. Στο έγγραφο Swagger που δημιουργήθηκε νωρίτερα, δεν υπήρχαν σχόλια XML. Εάν θέλετε να εμφανίσετε σχόλια XML στο έγγραφο Swagger, τότε απλώς γράψτε αυτά τα σχόλια στις μεθόδους δράσης του ελεγκτή σας.
Ας γράψουμε τώρα σχόλια για καθεμία από τις μεθόδους δράσης στο ValueController. Εδώ είναι η ενημερωμένη έκδοση του ValueController με σχόλια XML για καθεμία από τις μεθόδους δράσης.
[Διαδρομή ("api / [ελεγκτής]")] [ApiController]
δημόσια τάξη ValueController: ControllerBase
{
///
/// Λήψη μεθόδου δράσης χωρίς κανένα επιχείρημα
///
///
[HttpGet]
δημόσιο ActionResult Παίρνω() {
επιστροφή νέας συμβολοσειράς [] {"value1", "value2"};
}
///
/// Λήψη μεθόδου δράσης που δέχεται έναν ακέραιο ως επιχείρημα
///
///
///
[HttpGet ("{id}")]
δημόσια ActionResult Get (int id)
{
επιστροφή "τιμή";
}
///
/// Μέθοδος ανάρτησης δράσης για προσθήκη δεδομένων
///
///
[HttpPost]
public void Post (τιμή συμβολοσειράς [FromBody])
{
}
///
/// Βάλτε μέθοδο δράσης για τροποποίηση δεδομένων
///
///
///
[HttpPut ("{id}")]
public void Put (int id, [FromBody] τιμή συμβολοσειράς)
{
}
///
/// Διαγραφή μεθόδου δράσης
///
///
[HttpDelete ("{id}")]
δημόσιο κενό Διαγραφή (int id)
{
}
}
Ενεργοποιήστε τα σχόλια XML στο Swagger
Λάβετε υπόψη ότι το Swagger δεν εμφανίζει σχόλια XML από προεπιλογή. Πρέπει να ενεργοποιήσετε αυτήν τη λειτουργία. Για να το κάνετε αυτό, κάντε δεξί κλικ στο Project, επιλέξτε Properties και, στη συνέχεια, μεταβείτε στην καρτέλα Build. Στην καρτέλα Build, επιλέξτε την επιλογή "αρχείο τεκμηρίωσης XML" για να καθορίσετε τη θέση όπου θα δημιουργηθεί το αρχείο τεκμηρίωσης XML.
Θα πρέπει επίσης να καθορίσετε ότι τα σχόλια XML πρέπει να περιλαμβάνονται κατά τη δημιουργία του εγγράφου Swagger γράφοντας τον ακόλουθο κώδικα στη μέθοδο ConfigureServices.
c.IncludeXmlComments (@ "D: \ Projects \ SwaggerDemo \ SwaggerDemo \ SwaggerDemo.xml");
Και αυτό πρέπει να κάνετε για να ενεργοποιήσετε τα σχόλια XML στο Swagger.
Ορίστε τη διεύθυνση URL εκκίνησης για την εφαρμογή σε Swagger UI
Μπορείτε να αλλάξετε τη διεύθυνση URL εκκίνησης της εφαρμογής σας για να καθορίσετε ότι το UI Swagger θα φορτωθεί κατά την εκκίνηση της εφαρμογής. Για να το κάνετε αυτό, κάντε δεξί κλικ στο Project και επιλέξτε Properties. Στη συνέχεια, μεταβείτε στην καρτέλα εντοπισμού σφαλμάτων. Τέλος, καθορίστε την τιμή Launch Browser ως swagger όπως φαίνεται στο Σχήμα 2.
Όταν εκτελέσετε ξανά την εφαρμογή και μεταβείτε στη διεύθυνση Swagger URL, θα πρέπει να δείτε το περιβάλλον εργασίας χρήστη Swagger όπως φαίνεται στο σχήμα 3 παρακάτω. Σημειώστε τα σχόλια XML σε καθεμία από τις μεθόδους API αυτή τη φορά.
Το Swashbuckle είναι ένα εξαιρετικό εργαλείο για τη δημιουργία εγγράφων Swagger για το API σας. Το πιο σημαντικό, το Swashbuckle είναι εύκολο να διαμορφωθεί και να χρησιμοποιηθεί. Υπάρχουν πολλά περισσότερα που μπορείτε να κάνετε με το Swagger από ό, τι έχουμε δει εδώ. Μπορείτε να προσαρμόσετε το Swagger UI χρησιμοποιώντας Cascading Style Sheets, να εμφανίσετε τιμές enum ως τιμές συμβολοσειράς και να δημιουργήσετε διαφορετικά έγγραφα Swagger για διαφορετικές εκδόσεις του API σας, για να αναφέρουμε μόνο μερικές.
