Αυτό το άρθρο επεξεργάστηκε τελευταία φορά από το χρήστη QWERTYU στις 2019-4-12 14:24
ΕισαγωγήΜετά τη χρήση του asp.net Core για ανάπτυξη API, η σύνταξη τεκμηρίωσης API πρέπει να είναι μια επίπονη εργασία για τους προγραμματιστές, αλλά η τεκμηρίωση πρέπει να είναι γραμμένη και εάν δεν υπάρχουν συγκεκριμένες απαιτήσεις για τη μορφή της τεκμηρίωσης, η τελική τεκμηρίωση εξαρτάται εξ ολοκλήρου από τη διάθεση του προγραμματιστή. Ή να είστε πιο λεπτομερείς ή πιο απλοί. Υπάρχει λοιπόν ένας γρήγορος και αποτελεσματικός τρόπος για τη δημιουργία τεκμηρίωσης API; Η απάντηση είναι ναι, το Swagger είναι ένα από τα πιο δημοφιλή εργαλεία δημιουργίας τεκμηρίωσης REST API!
Γιατί να χρησιμοποιήσετε το Swagger ως εργαλείο δημιουργίας τεκμηρίωσης REST API- Το Swagger μπορεί να δημιουργήσει μια διαδραστική κονσόλα API που μπορούν να χρησιμοποιήσουν οι προγραμματιστές για να μάθουν γρήγορα και να πειραματιστούν με API.
- Το Swagger μπορεί να δημιουργήσει κώδικα SDK πελάτη για υλοποιήσεις σε μια ποικιλία διαφορετικών πλατφορμών.
- Τα αρχεία Swagger μπορούν να δημιουργηθούν αυτόματα από σχόλια κώδικα σε πολλές διαφορετικές πλατφόρμες.
- Το Swagger έχει μια ισχυρή κοινότητα με πολλούς ισχυρούς συνεισφέροντες.
Πώς να χρησιμοποιήσετε το Swagger για να δημιουργήσετε τεκμηρίωση API στον πυρήνα asp.net;- Το Swashbuckle.AspNetCore είναι ένα έργο ανοιχτού κώδικα που δημιουργεί τεκμηρίωση Swagger για ASP.NET Core Web API.
- Το NSwag είναι ένα άλλο έργο ανοιχτού κώδικα για την ενσωμάτωση του Swagger UI ή του ReDoc σε ASP.NET Core Web API. Παρέχει έναν τρόπο δημιουργίας κώδικα πελάτη C# και TypeScript για API.
Το παρακάτω είναι ένα παράδειγμα του Swashbuckle.AspNetCoreΠοια είναι τα συστατικά ενός Swashbuckle;- Swashbuckle.AspNetCore.Swagger: Εκθέτει το αντικείμενο SwaggerDocument ως μοντέλο αντικειμένου Swagger και ενδιάμεσο λογισμικό για τελικά σημεία JSON.
- Swashbuckle.AspNetCore.SwaggerGen: Μια γεννήτρια Swagger που δημιουργεί αντικείμενα SwaggerDocument απευθείας από διαδρομές, ελεγκτές και μοντέλα. Συχνά συνδυάζεται με ενδιάμεσο λογισμικό τελικού σημείου Swagger για αυτόματη έκθεση του Swagger JSON.
- Swashbuckle.AspNetCore.SwaggerUI: Μια ενσωματωμένη έκδοση του εργαλείου Swagger UI. Ερμηνεύει το Swagger JSON για τη δημιουργία προσαρμόσιμων, πλούσιων εμπειριών που περιγράφουν τη λειτουργικότητα των Web API. Περιλαμβάνει ενσωματωμένα εργαλεία δοκιμών για κοινές μεθόδους.
Πώς να εγκαταστήσετε το Swashbuckle με το vs2017;
Ο πρώτος τρόπος: εγκατάσταση από το παράθυρο της Κονσόλας Package Manager
- Μεταβείτε στις Προβολές > άλλη κονσόλα διαχείρισης πακέτων των Windows >
- Μεταβείτε στον κατάλογο που περιέχει το αρχείο TodoApi.csproj
- Εκτελέστε την ακόλουθη εντολή · Εγκατάσταση-Πακέτο Swashbuckle.AspNetCore
-
Δεύτερος τρόπος: Από το παράθυρο διαλόγου Διαχείριση πακέτων NuGet:- Κάντε δεξί κλικ στο έργο στην Εξερεύνηση λύσεων > Διαχείριση πακέτων NuGet
- Ορίστε την Πηγή Πακέτου σε nuget.org
- Πληκτρολογήστε "Swashbuckle.AspNetCore" στο πλαίσιο αναζήτησης
- Επιλέξτε το πακέτο Swashbuckle.AspNetCore από την καρτέλα Αναζήτηση και κάντε κλικ στο κουμπί Εγκατάσταση
-
Προσθήκη και διαμόρφωση ενδιάμεσου λογισμικού SwaggerΠαρουσιάστε πρώτα τον χώρο ονομάτων: Προσθέστε τη γεννήτρια Swagger στη συλλογή υπηρεσιών με τη μέθοδο Startup.ConfigureServices: σεΕκκίνηση.Διαμόρφωσημέθοδος, ενεργοποιήστε το ενδιάμεσο λογισμικό για την εξυπηρέτηση του παραγόμενου εγγράφου JSON και του Swagger UI:
Εκκινήστε την εφαρμογή και πλοηγηθείτε σε αυτήνhttps://localhost:<port>/swagger/v1/swagger.json。 Η τεκμηρίωση που προκύπτει και περιγράφει το τελικό σημείο εμφανίζεται σε μορφή JSON ως εξής.
Διαθέσιμοhttps://localhost:<port>/καυχησιολογίαΕντοπίστε το Swagger UI. Περιηγηθείτε στην τεκμηρίωση του API μέσω του Swagger UI όπως φαίνεται παρακάτω.
Για να εφαρμόσετε τη ρίζα (http://localhost:<port>/) για να παρέχετε το Swagger UI, βάλτε τοΠρόθεμα διαδρομήςΗ ιδιότητα έχει οριστεί σε μια κενή συμβολοσειρά:
Προηγμένη χρήση του Swagger (Προσαρμογή και επεκτάσεις)Χρησιμοποιήστε το Swagger για να προσθέσετε επεξηγηματικές πληροφορίες στην τεκμηρίωση του APIΟι ακόλουθες λειτουργίες ρύθμισης παραμέτρων εκτελούνται με τη μέθοδο AddSwaggerGen, η οποία προσθέτει πληροφορίες όπως πληροφορίες συντάκτη, άδειας χρήσης και περιγραφής: Οι πληροφορίες της έκδοσης εμφάνισης διεπαφής χρήστη wagger φαίνονται στην παρακάτω εικόνα: Προσθήκη σχολίων σε μεθόδους διεπαφήςΑς κάνουμε πρώτα κλικ στο API, ας επεκτείνουμε όπως φαίνεται στο παρακάτω σχήμα, δεν μπορούν να υπάρχουν σχόλια, πώς να προσθέσετε σχόλια; Προσθέστε σχόλια εγγράφου με τρία/όπως φαίνεται στην παρακάτω εικόνα, όπως φαίνεται παρακάτω Στη συνέχεια, εκτελέστε το έργο και επιστρέψτε στο swaggerUI για να δείτε αν εμφανίζεται το σχόλιο Ακόμα δεν εμφανίστηκε, μην ανησυχείτε, κοιτάξτε κάτω! Ενεργοποίηση σχολιασμών XMLΜπορείτε να ενεργοποιήσετε τα σχόλια XML χρησιμοποιώντας τις ακόλουθες μεθόδους: - Κάντε δεξί κλικ στο έργο στην Εξερεύνηση λύσεων και επιλέξτε Ιδιότητες
- Κοιτάξτε το πλαίσιο Αρχείο εγγράφου XML στην ενότητα Έξοδος της καρτέλας Δόμηση
-
Η ενεργοποίηση των σχολίων XML παρέχει πληροφορίες εντοπισμού σφαλμάτων για μη τεκμηριωμένους κοινούς τύπους και μέλη. Εάν εμφανιστούν πολλά προειδοποιητικά μηνύματα, για παράδειγμα, το ακόλουθο μήνυμα υποδεικνύει παραβίαση του κωδικού προειδοποίησης 1591:
Τι γίνεται αν έχετε ΙΨΔ και θέλετε να ακυρώσετε την προειδοποίηση; Μπορείτε να ακυρώσετε όπως φαίνεται στην παρακάτω εικόνα
Σημειώστε τη διαδρομή του αρχείου εγγράφου xml που δημιουργήθηκε παραπάνω,
Σημείωση: 1. Για λειτουργικά συστήματα Linux ή μη, τα ονόματα αρχείων και οι διαδρομές κάνουν διάκριση πεζών-κεφαλαίων. Για παράδειγμα, ένα αρχείο "SwaggerDemo.xml" λειτουργεί στα Windows, αλλά όχι στο CentOS. 2. Για να αποκτήσετε τη διαδρομή εφαρμογής, συνιστάται να χρησιμοποιήσετε το AppContext.BaseDirectory για να την αποκτήσετε Δημιουργήστε ξανά και εκτελέστε το έργο για να δείτε αν εμφανίζονται τα σχόλια Από την παραπάνω λειτουργία, μπορεί να συνοψιστεί ότι το Swagger UI εμφανίζει το <summary> εσωτερικό κείμενο των στοιχείων του παραπάνω κώδικα σχολίων ως μεγάλα σχόλια API! Φυσικά, μπορείτε επίσης να προσθέσετε το στοιχείο παρατηρήσεων στην τεκμηρίωση Λήψη οδηγιών. Μπορεί να συμπληρώσει <summary> τις πληροφορίες που καθορίζονται στο στοιχείο και να παρέχει μια πιο αξιόπιστη διεπαφή χρήστη Swagger. <remarks> Το περιεχόμενο του στοιχείου μπορεί να περιέχει κείμενο, JSON ή XML. Ο κωδικός έχει ως εξής: Δοκιμάστε τη διεπαφή api χρησιμοποιώντας το SwaggerUIΑς διορθώσουμε τη διεπαφή μέσω του SwaggerUI μέσω ενός μικρού παραδείγματος
- Κάντε κλικ σε μια διεπαφή API που πρέπει να δοκιμαστεί και, στη συνέχεια, κάντε κλικ στο κουμπί "Δοκιμάστε το" στα αριστερά και δεξιά των Παραμέτρων
- Εισαγάγετε μια παράμετρο στο πλαίσιο κειμένου παραμέτρου που εμφανίζεται, όπως φαίνεται στην παρακάτω εικόνα, εισαγάγετε την παράμετρο 2
- Κάντε κλικ στο κουμπί Εκτέλεση και θα εμφανιστεί η μορφοποιημένη απάντηση που φαίνεται παρακάτω, όπως φαίνεται στην παρακάτω εικόνα
Λοιπόν, αυτό είναι όλο για το σημερινό σεμινάριο σχετικά με τη χρήση του Swagger για τη δημιουργία τεκμηρίωσης api στο ASP.NET Core WebApi. Ελπίζω ότι θα σας βοηθήσει να μάθετε πώς να χρησιμοποιείτε το Swagger για να δημιουργείτε τεκμηρίωση API στο ASP.NET Core! περίληψηΑυτό το άρθρο ξεκινά με το σημείο πόνου της σύνταξης τεκμηρίωσης API με το χέρι και στη συνέχεια οδηγεί στο Swagger, ένα εργαλείο που δημιουργεί αυτόματα τεκμηρίωση API! Στη συνέχεια, μέσα από εύκολα κατανοητό κείμενο και εικόνες, θα δείξουμε πώς να χρησιμοποιήσετε το SwaggerUI για τη δημιουργία τεκμηρίωσης API σε ένα ASP.NET Core WebApi. Τέλος, θα παρουσιάσω μερικές προηγμένες χρήσεις του Swagger στο ASP.NET Core! Ελπίζω να σας βοηθήσει να χρησιμοποιήσετε το Swagger στο ASP.NET Core!
| 
Δημοσιεύτηκε στις 12/4/2019 2:14:46 μ.μ.
|
|
|
|
