Πρόσβαση και ενημέρωση της τεκμηρίωσης ενός εισαγόμενου API

Όταν εισάγετε μια προδιαγραφή, το Restorm δεν δημιουργεί μόνο αιτήματα: διατηρεί την τεκμηρίωση του API — περιγραφές, μοντέλα, σχήματα ασφαλείας, παραδείγματα, απαριθμήσεις — και τη συνδέει με τον φάκελο μεταβλητών που δημιουργείται από την εισαγωγή.

Πρόσβαση στην τεκμηρίωση

Η καρτέλα Docs του φακέλου μεταβλητών

Είναι η κύρια προβολή. Ανοίξτε τον φάκελο μεταβλητών που προέκυψε από την εισαγωγή: η γραμμή υποκαρτελών του φέρει μια καρτέλα Docs, δίπλα στις Περιβάλλοντα, Προσαρμοσμένες μεταβλητές και Σημειώσεις.

Η καρτέλα εμφανίζεται μόνο αν ο φάκελος προέρχεται από εισαγωγή — ένας φάκελος μεταβλητών που δημιουργήσατε στο χέρι δεν έχει τεκμηρίωση να εμφανίσει.

Οι άλλες είσοδοι

Από	Τι λαμβάνετε
Την καρτέλα Docs ενός αιτήματος	Την τεκμηρίωση αυτής και μόνο της λειτουργίας — χωρίς πίνακα περιεχομένων ούτε μπλοκ γενικών πληροφοριών. Εμφανίζεται μόνο αν η λειτουργία εντοπιστεί στην προδιαγραφή
Την καρτέλα Docs ενός απλού φακέλου	Την τεκμηρίωση περιορισμένη στις λειτουργίες που περιέχει αυτός ο φάκελος
Την υποκαρτέλα υποδοχής του φακέλου μεταβλητών	Την κάρτα Δείτε την τεκμηρίωση — «Περιηγηθείτε στην τεκμηρίωση του API, στα μοντέλα και στα endpoints»
Την οθόνη υποδοχής (κάρτα API)	Τον γρήγορο σύνδεσμο Τεκμηρίωση
Τη μηχανή αναζήτησης της γραμμής τίτλου	Μια προεπισκόπηση της τεκμηρίωσης όταν περνάτε τον δείκτη πάνω από ένα αποτέλεσμα

Τι περιέχει η προβολή

Από πάνω προς τα κάτω:

• τον τίτλο του API και την περιγραφή του·
• ένα μπλοκ πληροφοριών: Version, Source format (με σύνδεσμο προς τη διεύθυνση URL προέλευσης), Server (σχήματα, υπολογιστής, βασική διαδρομή), Contact, License, Terms of service, External docs·
• μια ενότητα ανά ετικέτα, με την περιγραφή της·
• ένα μπλοκ ανά λειτουργία: μέθοδο και διεύθυνση URL, περίληψη, κουκκίδα ομάδας, σήμα deprecated όπου χρειάζεται, ενότητα Security (τύπος σχήματος, ροή OAuth 2, εμβέλειες), και ένα αναδιπλούμενο Example payload·
• τους πίνακες Parameters και Responses (οι κωδικοί κατάστασης είναι χρωματισμένοι)·
• Models — έναν διαδραστικό γράφο των σχημάτων, με δυνατότητα πλοήγησης και ζουμ·
• Polymorphism — τις συνθέσεις oneOf / anyOf / allOf·
• Enums — τις απαριθμήσεις, συγχωνευμένες με εκείνες του φακέλου.

Note

Οι τίτλοι αυτών των ενοτήτων (Models, Enums, Parameters, Responses, Security, Example payload) εμφανίζονται στα αγγλικά σε όλες τις γλώσσες της εφαρμογής. Αναφέρονται εδώ ως έχουν ώστε να τους αναγνωρίσετε στην οθόνη.

Δημιουργία αιτήματος από την τεκμηρίωση

Κάθε μπλοκ λειτουργίας φέρει ένα κουμπί + Add που δημιουργεί ένα αίτημα προδιαμορφωμένο γι’ αυτή τη λειτουργία. Είναι ο συντομότερος δρόμος όταν μια εισαγωγή ήταν μερική, ή όταν μια λειτουργία μόλις εμφανίστηκε στην προδιαγραφή.

Πλοήγηση και αναζήτηση

Ένας πίνακας περιεχομένων είναι αγκυρωμένος στα δεξιά — ενότητες Overview, Operations, Models, Enums — αναδιπλούμενος και με δυνατότητα αλλαγής μεγέθους. Αν κάνετε κλικ σε ένα μοντέλο, η σελίδα κυλά ως τον γράφο και κεντράρει τον αντίστοιχο κόμβο.

Συντόμευση	Αποτέλεσμα
Ctrl+F / Cmd+F	Ανοίγει την αναζήτηση μέσα στην τεκμηρίωση
F3 / Enter	Επόμενη αντιστοιχία
Shift+F3 / Shift+Enter	Προηγούμενη αντιστοιχία
Esc	Κλείνει την αναζήτηση

Ένας μετρητής δείχνει τη θέση μέσα στα αποτελέσματα.

Ενημέρωση της τεκμηρίωσης

Μια προδιαγραφή εξελίσσεται. Το Restorm ξέρει να ανακτά την πηγή και να εφαρμόζει τη διαφορά — τεκμηρίωση και αιτήματα — χωρίς να καταστρέψει τη δουλειά σας.

Μόνο για τις εισαγωγές μέσω διεύθυνσης URL

Ο επανασυγχρονισμός είναι διαθέσιμος μόνο αν ο φάκελος εισήχθη από μια διεύθυνση URL. Μια εισαγωγή από αρχείο ή με επικόλληση δεν καταγράφει πηγή, και το κουμπί ανανέωσης δεν εμφανίζεται: η υποκαρτέλα υποδοχής δείχνει τότε «Αυτός ο φάκελος δεν δημιουργήθηκε από εισαγώγιμη πηγή.»

Αυτή η διεύθυνση URL δεν είναι τροποποιήσιμη εκ των υστέρων μέσα από τη διεπαφή. Για να αλλάξετε πηγή, κάντε ξανά εισαγωγή.

Πού βρίσκεται το κουμπί

Δύο ισοδύναμες είσοδοι:

1. η υποκαρτέλα υποδοχής του φακέλου μεταβλητών, ενότητα Ενημερώσεις προδιαγραφής API — εμφανίζει το URL, την Τελευταία εισαγωγή και τον Τελευταίο έλεγχο, και φέρει το κουμπί Ανανέωση·
2. το δεξί κλικ στον φάκελο μέσα στο πλαϊνό δέντρο → Ανανέωση.

Δεν υπάρχει αυτόματος έλεγχος

Το Restorm δεν παρακολουθεί τις προδιαγραφές σας στο παρασκήνιο και δεν θα σας ειδοποιήσει ότι υπάρχει νέα έκδοση. Ο έλεγχος ενεργοποιείται πάντα από εσάς.

Τι συμβαίνει

1. Ένα παράθυρο «Ανανέωση της προδιαγραφής…» εμφανίζεται κατά την ανάκτηση. Οι {{variables}} της διεύθυνσης URL και των κεφαλίδων επιλύονται, και η συνδεδεμένη διαδρομή ταυτοποίησης εκτελείται εκ των προτέρων.
2. Το Restorm συγκρίνει ένα αποτύπωμα της πηγής που ανακτήθηκε με εκείνο που καταγράφηκε στην τελευταία εισαγωγή.
3. Δεν άλλαξε τίποτα → «Η προδιαγραφή του API είναι ενημερωμένη.», και τελειώσαμε.
4. Κάτι άλλαξε (ή η ανάκτηση απέτυχε) → ανοίγει ο οδηγός επανασυγχρονισμού.

Ο οδηγός

• Η διεύθυνση URL προέλευσης εμφανίζεται μόνο για ανάγνωση.
• Μια κουκκίδα επιτρέπει να συνδέσετε, να τροποποιήσετε ή να αποσυνδέσετε μια διαδρομή ταυτοποίησης, και ένα υπομενού Custom headers να προσθέσετε σταθερές κεφαλίδες που ξαναπαίζονται σε κάθε ανανέωση.
• Δύο καρτέλες προεπισκόπησης:
  • Routes — το δέντρο των λειτουργιών που βρέθηκαν στη νέα έκδοση, με φίλτρο και επιλογή. Οι λειτουργίες που υπάρχουν ήδη στον φάκελό σας είναι κλειδωμένες και πάντα επιλεγμένες· επιλέγετε μόνο ποιες από τις νέες θα προσθέσετε·
  • Documentation — η τεκμηρίωση της νέας έκδοσης, μόνο για ανάγνωση, πριν επικυρώσετε.
• Το κουμπί επικύρωσης δείχνει τον αριθμό των νέων λειτουργιών που έχουν επιλεγεί, για παράδειγμα Apply update (3).

Note

Ο οδηγός εμφανίζεται σήμερα στα αγγλικά όποια κι αν είναι η γλώσσα της εφαρμογής («Refresh from source», «Apply update», καρτέλες «Routes» και «Documentation»). Οι αγγλικοί τίτλοι αναφέρονται επομένως εδώ ως έχουν.

Τι τροποποιείται και τι όχι

Αυτό είναι το σημαντικό σημείο: η προδιαγραφή έχει την τελευταία λέξη για ό,τι περιγράφει, εσείς έχετε την τελευταία λέξη για τα υπόλοιπα.

Στοιχείο	Συμπεριφορά
Όνομα ενός αιτήματος	Ποτέ δεν τροποποιείται
Μέθοδος και διεύθυνση URL	Ποτέ δεν τροποποιούνται
Υπάρχουσες παράμετροι, κεφαλίδες και παράμετροι διαδρομής	Διατηρούνται ως έχουν — τιμή, περιγραφή, ενεργοποίηση
Παράμετροι που προστίθενται από την προδιαγραφή	Προστίθενται, με την προεπιλεγμένη τιμή της προδιαγραφής ή κενές
Παράμετροι που αφαιρέθηκαν από την προδιαγραφή	Διατηρούνται στο αίτημα
Νέα λειτουργία	Προστίθεται στο σημείο όπου θα την τοποθετούσε μια καινούργια εισαγωγή (μαζί με τον φάκελο ετικέτας)
Λειτουργία που σημαίνεται ως παρωχημένη από την προδιαγραφή	Επισημαίνεται· εμφανίζεται ξεθωριασμένη στο δέντρο
Λειτουργία που εξαφανίστηκε από την προδιαγραφή	Επισημαίνεται ως αφαιρεθείσα· εμφανίζεται διαγραμμένη στο δέντρο, παραμένει εκτελέσιμη και δεν διαγράφεται ποτέ
Τεκμηρίωση API και απαριθμήσεις	Αντικαθίστανται εξ ολοκλήρου από τη νέα έκδοση — αυτό είναι που ανανεώνει την καρτέλα Docs

Τίποτα δεν διαγράφεται ποτέ από το δέντρο σας: μια λειτουργία που εξαφανίζεται από την πηγή σημαίνεται, δεν σβήνεται.

Αν η πηγή απαιτεί ταυτοποίηση

Μια απόκριση 401 ή 403 ανοίγει τον οδηγό με το μήνυμα σφάλματος να εμφανίζεται ως έχει (για παράδειγμα HTTP 401: Unauthorized). Συνδέστε μια διαδρομή ταυτοποίησης ή προσθέστε σταθερές κεφαλίδες, και η προεπισκόπηση ξεκινά ξανά.

Επανασυγχρονίσιμες μορφές

Δώδεκα μορφές διαθέτουν επανασυγχρονισμό: Swagger 2.0, OpenAPI 3.x, GraphQL, gRPC, SOAP (WSDL), OData, AsyncAPI, Postman, Insomnia, Bruno, OpenRPC και Smithy.

Για όλες τις υπόλοιπες, μια νέα εισαγωγή δημιουργεί νέο δέντρο. Η πλήρης λίστα βρίσκεται στο Ενημέρωση από την πηγή.