# OpenAPI :badge[Neu in Clay 5]{tip}

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](https://clay-doc.github.io/clay-example-repo/de/api/petstore.md) dieser Website entsteht so, aus der Beispiel-API von Swagger.

```yaml [clay.yaml]
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.

> [!TIP]
> Ein Dokument, das woanders liegt, etwa eines, das deine API ausliefert, lädt [`generate`](https://clay-doc.github.io/clay-example-repo/de/writing/generated-docs.md) vor jedem Build herunter: `curl -o openapi/api.json https://api.example.com/openapi.json`.

## Die Seiten

| Seite | Was sie zeigt |
|-------|---------------|
| Übersicht | Version und Beschreibung, die Server, jede Art der Authentifizierung, die Operationen nach Tag und das Dokument zum Herunterladen |
| Tag | Seine Beschreibung und seine Operationen |
| Operation | Eine Request-Zelle zum Ausprobieren, die nötigen Zugangsdaten, Parameter, Anfrage-Body und Antworten (mit Headern, Beispielen und Links) und ihre Callbacks |
| Webhook | Die Anfrage, die die API an deinen Server sendet |
| Schema | Seine Eigenschaften, auch verschachtelte, und ein Beispiel |

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:

```md
[Finds Pets by status.](/de/api/petstore/pet/find-pets-by-status)

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

::: request petstore findPetsByStatus
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.

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

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

Wie in einem Notebook wählt ein Klick eine Zelle aus, und <kbd>Strg</kbd> + <kbd>Enter</kbd> (<kbd>⌘</kbd> + <kbd>Enter</kbd> 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.

| Im Dokument | In der Zelle |
|-------------|--------------|
| `apiKey` im Header oder in der Query | Der Schlüssel |
| `http`: `basic`, `bearer` und andere | Benutzername und Passwort, oder das Token |
| `oauth2` | Anmelden mit dem Authorization-Code-Flow (mit PKCE), implizit, mit Client Credentials oder Passwort; oder ein Token einfügen |
| `openIdConnect` | Anmelden beim Anbieter, den sein Discovery-Dokument nennt |
| `mutualTLS` | Der Browser fragt nach dem Zertifikat |

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.

> [!NOTE]
> Anfragen gehen vom Browser des Lesers direkt an die API, deshalb muss die API Anfragen von deiner Website erlauben ([CORS](https://developer.mozilla.org/de/docs/Web/HTTP/Guides/CORS)); der Petstore erlaubt alle Websites. Wenn nicht, sagt die Zelle es. Browser lassen eine Seite außerdem keine eigenen Cookies senden: Ein API-Schlüssel in einem Cookie steht nur im Code.

## Versionen

Wenn du mit [`clay version`](https://clay-doc.github.io/clay-example-repo/de/organizing/versions.md) 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.

```md
::: 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)
:::
```

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

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

::: endpoints
- `GET /pet/{petId}` [Haustier nach ID finden](https://clay-doc.github.io/clay-example-repo/de/api/petstore/pet/get-pet-by-id.md)
:::

## Für Agenten

Im [Markdown einer Seite](https://clay-doc.github.io/clay-example-repo/de/features/ai-and-agents.md) ist eine Request-Zelle ein curl-Befehl mit einem Link zu ihrer Operation, und `llms.txt` führt die Seiten jeder API auf.

---

All pages of these docs, as Markdown for language models: https://clay-doc.github.io/clay-example-repo/de/llms.txt