# API-Design und Dokumentation mit OpenAPI Workshop

- Datum: Di, 10.02.2026
- Startzeit: 08:30 Uhr
- Raum: A108

## Ressourcen

- [Workshop-Folien](./Ressourcen/IWS-OpenAPI.pptx.pdf)
- [YAML Cheatsheet](./Ressourcen/YAML_Cheatsheet.pdf)
- API Szenario: _pending_

## Installationsanleitung

Benötigte Hardware: Eigener Laptop

- [Visual Studio Code](#visual-studio-code)
- [Visual Studio Code Extensions](#visual-studio-code-extensions)
- [Python](#python)
- [Python Packages](#python-packages)
- [Abhängigkeiten installieren](#abhängigkeiten-installieren)
- [Java](#java)
- [Tools ausführen](#tools-ausführen)

### Visual Studio Code

Installationsanleitung hier zu finden: [https://code.visualstudio.com/](https://code.visualstudio.com/)

### Visual Studio Code Extensions

- YAML von RedHat (`redhat.vscode-yaml`)
- OpenAPI (Swagger) Editor von 42crunch (`42crunch.vscode-openapi`)
- Python von Microsoft (`ms-python.python`)

### Python

#### Download

Lade Python von der offiziellen Website herunter:
👉 https://www.python.org/downloads/

**Empfohlene Version:**

- Python **3.11 oder neuer**

#### Installation

- macOS / Windows: Installer ausführen
- **Wichtig (Windows):**
    ☑️ _“Add Python to PATH”_ aktivieren
- Linux: Normalerweise ist Python schon installiert

#### Installation prüfen

```bash
python --version
```

#### Projektordner vorbereiten

```bash
mkdir openapi-workshop
cd openapi-workshop
```

#### Virtuelle Umgebung erstellen (empfohlen)

**Virtuelle Umgebung anlegen**

```bash
python -m venv .venv
```

**Aktivieren**
macOS / Linux

```bash
source .venv/bin/activate
```

Windows (PowerShell)

```powershell
.venv\Scripts\activate
```

Wenn alles korrekt ist, siehst du im Terminal:

```text
(.venv)
```

#### pip aktualisieren

```bash
python -m pip install --upgrade pip
```

### Python Packages

Wir verwenden:

- **FastAPI** – API Framework
- **Uvicorn** – ASGI Server
- **uv**

```bash
python -m pip install fastapi uvicorn uv
```

Installation prüfen:

```bash
python -m pip show fastapi uvicorn uv
```

### Abhängigkeiten installieren

```sh
uv init
uv add openapi-generator-cli
```

### Java

[https://jdk.java.net/25/](https://jdk.java.net/25/)

### Tools ausführen

#### FastAPI-Anwendung

**Datei `code_first.py`**

```python
from fastapi import FastAPI

app = FastAPI()

@app.get("/")
def root():
    return {
        "status": "ok",
        "docs": "/docs",
        "openapi": "/openapi.json"
    }
```

**Server starten**
⚠️ **FastAPI wird nicht mit `python code_first.py` gestartet**,  
sondern mit **`uvicorn`**.

```bash
python -m uvicorn code_first:app --reload
```

**API aufrufen**
Im Browser:

- **Swagger UI (interaktive API-Dokumentation):**  
    http://127.0.0.1:8000/docs
- **OpenAPI JSON:**  
    http://127.0.0.1:8000/openapi.json

**Server stoppen**
Im Terminal:

```text
CTRL + C
```

### OpenAPI Generator CLI

```sh
uv run openapi-generator-cli
```