IWS-OpenAPI/README.md

API-Design und Dokumentation mit OpenAPI Workshop

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

Ressourcen

• Workshop-Folien: pending
• YAML Cheatsheet
• API Szenario: pending

Installationsanleitung

Benötigte Hardware: Eigener Laptop

• Visual Studio Code
• Visual Studio Code Extensions
• Python
• Python Packages
• Abhängigkeiten installieren
• Java
• Tools ausführen

Visual Studio Code

Installationsanleitung hier zu finden: 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

python --version

Projektordner vorbereiten

mkdir openapi-workshop
cd openapi-workshop

Virtuelle Umgebung erstellen (empfohlen)

Virtuelle Umgebung anlegen

python -m venv .venv

Aktivieren macOS / Linux

source .venv/bin/activate

Windows (PowerShell)

.venv\Scripts\activate

Wenn alles korrekt ist, siehst du im Terminal:

(.venv)

pip aktualisieren

python -m pip install --upgrade pip

Python Packages

Wir verwenden:

• FastAPI – API Framework
• Uvicorn – ASGI Server
• uv

python -m pip install fastapi uvicorn uv

Installation prüfen:

python -m pip show fastapi uvicorn uv

Abhängigkeiten installieren

uv add openapi-generator-cli

Java

https://jdk.java.net/25/

Tools ausführen

FastAPI-Anwendung

Datei code_first.py

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.

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:

CTRL + C

OpenAPI Generator CLI

uv run openapi-generator-cli