176 lines
2.9 KiB
Markdown
176 lines
2.9 KiB
Markdown
# 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](./Szenario/OpenAPI-Workshop-FoodExpress.md)
|
||
|
||
## 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
|
||
```
|