OpenAPI Neu in Clay 5

Nenne in clay.yaml ein OpenAPI-Dokument, und Clay macht eine Seite für jede seiner Operationen, Tags und Schemas. Sie stehen in der Navigation unter der Dokumentation, unter einer Linie, und werden durchsucht, geprüft und von Agenten gelesen wie jede andere Seite. Die Petstore-API dieser Website entsteht so, aus der Beispiel-API von Swagger.

openapi:
  - spec: openapi/petstore.yaml
    title: Petstore API     # Standard: der Titel des Dokuments
    route: api/petstore     # Standard: api/ und der Name der Datei
    icon: fa-solid fa-paw   # Standard: ein Stecker

Clay liest OpenAPI 3.0 und 3.1 sowie Swagger 2.0, als YAML oder JSON. Verweise ($ref) dürfen zu anderen Dateien des Projekts führen. clay check und clay build --strict melden, was die OpenAPI-Spezifikation nicht erlaubt, mit der Stelle im Dokument.

#Die Seiten

Schemas mit eigenem Namen sind überall mit ihrer Seite verlinkt, so führt die category eines Haustiers zur Seite von Category. Operationen zeigen in der Navigation ihre Methode; veraltete sind durchgestrichen. Die Oberflächentexte der Seiten sind in der Sprache jeder Ausgabe; die Texte des Dokuments bleiben, wie sie sind.

#Request-Zellen

Eine Request-Zelle ist eine Anfrage, die man auf der Seite ausfüllt und ausführt, wie eine Zelle eines Notebooks. Jede Operation hat eine auf ihrer Seite. In eigenen Seiten nennst du die API und die Operation, und die Startwerte in YAML:

::: request petstore findPetsByStatus
status: available
:::

curl 'https://petstore3.swagger.io/api/v3/pet/findByStatus?status=available' \
  -H 'Authorization: Bearer <token>'

[
  {
    "id": 10,
    "name": "doggie",
    "category": {
      "id": 1,
      "name": "Dogs"
    },
    "photoUrls": [
      "string"
    ],
    "tags": [
      {
        "id": 0,
        "name": "string"
      }
    ],
    "status": "available"
  }
]

Die Operation wird mit ihrer operationId genannt, oder mit Methode und Pfad: ::: request petstore GET /pet/{petId}. body: gibt einen Anfrage-Body vor, server: wählt einen der Server.

Ohne API enthält eine Zelle eine ausgeschriebene Anfrage, wie in einer .http-Datei: Methode und Adresse, die Header, eine leere Zeile und der Body. Leser können alles davon ändern.

::: request
GET https://petstore3.swagger.io/api/v3/pet/10
Accept: application/json
:::

curl 'https://petstore3.swagger.io/api/v3/pet/10' \
  -H 'Accept: application/json'

Wie in einem Notebook wählt ein Klick eine Zelle aus, und Strg + Enter (⌘ + Enter auf dem Mac) führt die ausgewählte aus. Ein Anfrage-Body wird beim Schreiben eingefärbt, und jeder Medientyp behält seinen eigenen: Der Wechsel zu application/xml zeigt ein XML-Beispiel. Die Antwort erscheint darunter: ihr Status, wie lange sie gedauert hat, ihre Header und ihr Body, JSON in Farben und Bilder als Bilder. Bis dahin zeigt die Zelle die Beispielantwort aus dem Dokument. curl, JavaScript und Python zeigen die Anfrage als Code zum Kopieren.

#Zugangsdaten

Leser geben Schlüssel, Passwörter und Tokens einmal pro API ein, wie mit dem Authorize-Knopf von Swagger UI: in der Übersicht der API unter Authentifizierung, oder mit Autorisieren in einer beliebigen Zelle, die die Methoden ihrer Operation zeigt, jede in einem Tab. Jede Zelle der API nutzt sie. Sie bleiben im Browser-Tab, außer der Leser wählt Auf diesem Gerät merken, und werden nur an die API selbst gesendet. Codebeispiele zeigen stattdessen Platzhalter.

Die Anmeldung über die Seite des Anbieters kehrt zu _clay/oauth-callback.html der Website zurück, z. B. https://clay-doc.github.io/clay-example-repo/_clay/oauth-callback.html; trag diese Adresse beim Anbieter als Weiterleitungs-URL ein.

#Versionen

Wenn du mit clay version eine Version speicherst, behält sie ihre APIs, wie sie an diesem Tag sind: Clay kopiert ihre Dokumente, und die Dateien, auf die sie verweisen, nach docs/<version>/_openapi/, mit ihren Einstellungen in apis.yaml daneben. Die API-Seiten und Request-Zellen der Version nutzen diese Kopien, während die aktuelle Dokumentation dem Dokument folgt, wie es sich ändert.

#Felder und Endpunkte

Die API-Seiten sind in Markdown geschrieben, mit zwei Komponenten, die du auch in eigenen Seiten nutzen kannst: ::: fields zeigt eine Liste von Namen mit ihrem Typ und Merkmalen: der Name als Code, dann der Typ, dann fett für erforderlich, kursiv für andere Merkmale und durchgestrichen für veraltet. ::: endpoints zeigt eine Liste von Operationen mit ihrer Methode.

::: fields
- `name` string **erforderlich**

  Wie das Haustier heißt.
- `status` string *nur lesbar*
:::

::: endpoints
- `GET /pet/{petId}` [Haustier nach ID finden](/de/api/petstore/pet/get-pet-by-id)
:::

• GET/pet/{petId}Haustier nach ID finden

#Für Agenten

Im Markdown einer Seite ist eine Request-Zelle ein curl-Befehl mit einem Link zu ihrer Operation, und llms.txt führt die Seiten jeder API auf.