Specs

Auf der Seite „Specs“ entwirfst und verwahrst du den Vertrag einer API: OpenAPI-Dokumente (OpenAPI 3.0 und 3.1 sowie Swagger 2.0) und die .proto-Dateien von gRPC-Diensten. Echolot prüft eine Spec, während du sie bearbeitest, macht daraus Anfragen, die mit ihr im Gleichschritt bleiben, und stellt sie als Mock bereit, bevor es die API gibt.

Öffne sie mit Specs in der Modulauswahl der Seitenleiste oder mit ⌘3.

Specs im ArbeitsbereichCopy Anchor Link

Specs sind Dateien im Ordner specs des Arbeitsbereichs und kommen deshalb mit allem anderen in Git. Das Beispiel Alpenglow hat drei: alpenglow.yaml (das OpenAPI-Dokument des Shops), shop.graphql und inventory.proto. Die Seite „Specs“ listet OpenAPI-Dokumente unter Specs und .proto-Dateien unter Proto-Dateien. GraphQL-Schemas im Ordner verwenden GraphQL-Anfragen; sie werden hier nicht aufgeführt.

Das + im Kopf von Specs in der Seitenleiste fügt eine hinzu:

Ein OpenAPI-Dokument mit Datei › Importieren … zu importieren ist etwas anderes: Das erzeugt Anfragen daraus, keine Spec zum Bearbeiten.

Klicke eine Spec mit der rechten Maustaste an für Anfragen erzeugen, Im Finder anzeigen, Exportieren (Als YAML … oder Als JSON …) und Löschen …. Löschen fragt zuerst nach und legt die Datei in den Papierkorb; Dateien, auf die sie verweist, bleiben bestehen, ebenso Mocks davon.

Die GliederungCopy Anchor Link

Klicke eine Spec an, um sie zu öffnen. Unter der Liste zeigt die Seitenleiste ihre Gliederung:

• Überblick, also Titel, Version und Beschreibung.
• ENDPUNKTE, jede Operation mit ihrer Methode und ihrem Pfad. Veraltete sind durchgestrichen. Halte den Zeiger auf einen, um seine Zusammenfassung zu sehen.
• SCHEMAS, die wiederverwendbaren Schemas.
• Dateien, wenn die Spec auf andere Dateien verweist (siehe Specs auf mehrere Dateien verteilt).

Klicke einen Eintrag an, um ihn zu öffnen: Im visuellen Editor öffnet sich seine Karte und scrollt ins Bild; im Code springt der Editor zu seiner Zeile.

Visuell und CodeCopy Anchor Link

Der Schalter Editor im Seitenkopf bestimmt, wie du die geöffnete Spec siehst:

• Visuell: Karten für Überblick, Server, Endpunkte und Schemas, bearbeitet mit Feldern und Menüs.
• Code: das Dokument als YAML oder JSON, mit Zeilennummern.

Beide bearbeiten denselben Text, und Echolot sichert ihn kurz nach jeder Änderung. Eine Spec bearbeiten behandelt beide.

ProblemeCopy Anchor Link

Echolot prüft die Spec mit dem Linter, während du sie bearbeitest. Die Leiste über dem Editor zeigt Keine Probleme oder die Anzahl der Fehler und Warnungen. Eine rote Fehlerzahl steht außerdem neben der geöffneten Spec in der Seitenleiste.

Klicke darauf für die Liste: zuerst Fehler, dann Warnungen und Hinweise, jeweils mit ihrer Zeile. Wähle einen Eintrag, um zu dieser Zeile zu springen. Ist die Liste leer, steht dort, dass das Dokument der OpenAPI-Spezifikation entspricht und jede Referenz aufgelöst wird.

Wonach der Linter unter anderem sucht:

• Eine openapi-Version, die Echolot liest, info mit Titel und Version und Pfade, die mit / beginnen.
• Pfadparameter, die im Pfad stehen und mit required: true markiert sind, und Parameter, die nicht doppelt definiert sind.
• Eine Beschreibung bei jeder Antwort und Operations-IDs, die nur einmal vorkommen.
• Oben deklarierte Tags, definierte Sicherheitsschemata, Arrays mit items und Enums mit Werten.
• Referenzen, die auf etwas zeigen, in dieser Datei oder in einer anderen in specs.
• Kein servers: Anfragen, die aus der Spec entstehen, beginnen dann mit {{baseUrl}}, was du selbst festlegst.

Das Befehlszeilenwerkzeug führt denselben Linter in CI aus: siehe echolot spec.

Specs auf mehrere Dateien verteiltCopy Anchor Link

Eine Spec kann Teile anderer Dateien mit $ref einbinden, etwa $ref: schemas/pet.yaml#/Pet. Die Dateien müssen im Ordner specs des Arbeitsbereichs liegen. Die Seitenleiste listet sie unter Dateien: Klicke eine an, um sie in Code zu öffnen. Halte im Code-Editor den Zeiger auf ein $ref, um zu sehen, worauf es zeigt, und klicke mit ⌘ darauf, um dorthin zu springen, in dieser oder in der anderen Datei.

Echolot liest die Teile überall zusammen, wo es die Spec verwendet: beim Linter, beim Erzeugen von Anfragen, bei Mocks. Exportierst du die Spec, werden die Dateien, auf die sie verweist, in die eine Datei geschrieben, die du sicherst.

ExportierenCopy Anchor Link

Exportieren in der Leiste über dem Editor (Als YAML exportieren … oder Als JSON exportieren …) sichert die Spec als eine Datei außerhalb des Arbeitsbereichs, mit den Dateien, auf die sie verweist, hineingeschrieben. Nicht gesicherte Änderungen werden zuerst gesichert, der Export entspricht also dem, was der Editor zeigt.

Anfragen, die der Spec folgenCopy Anchor Link

Anfragen erzeugen in der Leiste über dem Editor legt einen nach der Spec benannten Ordner mit einer Anfrage für jeden Endpunkt an und öffnet die erste. Der Ordner folgt der Spec: Ändert sich die Spec, kannst du die Änderungen auf seine Anfragen anwenden, ohne zu verlieren, was du in ihnen bearbeitet hast.

Folgt ein Ordner der Spec, wird aus dem Knopf Anfragen, ein Menü mit „Ordner“ auf Änderungen prüfen … für jeden Ordner, der ihr folgt, und Weiteren Ordner erzeugen. Das Prüfen öffnet OpenAPI-Sync, das auflistet, was Neu in der Spec, In der Spec geändert und Nicht mehr in der Spec ist. Hake die gewünschten Änderungen an und klicke auf 1 Änderung anwenden (oder 3 Änderungen anwenden usw.). Deine Änderungen bleiben immer erhalten; wo du und die Spec dasselbe geändert haben, bleibt deine Fassung. Ist eine Operation verschwunden, kommt ihre Anfrage in den Papierkorb, es sei denn, du hast sie bearbeitet: Dann bleibt sie und folgt der Spec nicht mehr. Trennen beendet, dass der Ordner der Spec folgt, und lässt seine Anfragen, wie sie sind.

Ein Ordner kann auch einer Spec außerhalb des Arbeitsbereichs folgen, einer Datei oder einer URL: Klicke den Ordner in der Seitenleiste der Anfragen mit der rechten Maustaste an und wähle Mit OpenAPI-Spec verknüpfen …. Das Befehlszeilenwerkzeug prüft und wendet Änderungen mit echolot spec check und echolot spec apply an.