OpenAPI und Swagger für API-Dokumentation
OpenAPI ist der Standard für die maschinenlesbare Beschreibung von REST APIs und bildet die Grundlage für interaktive Dokumentation, Mock-Server und Codegenerierung.
Kompakte Beschreibung
OpenAPI ist ein Spezifikationsformat für REST APIs, das Endpunkte, Methoden, Parameter, Request- und Response-Schemas, Statuscodes, Fehlerformate und Sicherheitsmechanismen beschreibt. Es wird meist in YAML oder JSON geschrieben und dient als Single Source of Truth für Entwickler, Tester, Client-Generatoren und Dokumentation. Swagger ist ein historischer Name und bezeichnet heute eine Reihe von Tools rund um OpenAPI, darunter Swagger UI, Swagger Editor und Swagger Codegen. OpenAPI ermöglicht API First Design, automatisierte Tests und die Erstellung von interaktiven API-Dokumentationen. Eine gute OpenAPI-Spezifikation ist vollständig, konsistent und mit Beispielen angereichert, sodass Nutzer die API verstehen und ausprobieren können, ohne den Code lesen zu müssen.
Wichtige Komponenten
OpenAPI Version
OpenAPI wird in Versionen 2.0, 3.0 und 3.1 unterstützt. Version 3.0 und 3.1 bieten mehr Flexibilität als 2.0, unter anderem bei Request- und Response-Definitionen, Links und Callbacks. Du solltest bei Neuprojekten eine aktuelle Version verwenden und Ältere nur aus Kompatibilitätsgründen pflegen.
Info und Metadaten
Der info-Block enthält grundlegende Angaben wie Titel, Version, Beschreibung und Kontaktinformationen. Diese Metadaten sind wichtig für die Identifikation der API und die automatisierte Dokumentation.
Server URLs
Server-URLs definieren, unter welchen Adressen die API erreichbar ist. Du kannst mehrere Umgebungen wie Development, Staging und Production angeben. Variablen ermöglichen es, Teile der URL dynamisch zu gestalten.
Paths und Operationen
Paths beschreiben die Endpunkte der API. Jeder Path kann mehrere Operationen enthalten, beispielsweise get, post, put, delete, patch. Jede Operation umfasst Summary, Description, Tags, Parameter, Request Body und Responses.
Components und Schemas
Components enthalten wiederverwendbare Definitionen wie Schemas, Parameters, Responses, Headers und Security Schemas. Schemas definieren die Datenstruktur von Requests und Responses mit Typen, Pflichtfeldern, Formaten und Beispielen.
Parameter
Parameter können in Path, Query, Header oder Cookie übertragen werden. Sie werden mit Name, Typ, Format, Required und Description definiert. Beispiele und Validierungsregeln wie minLength oder pattern verbessern die Qualität.
Request Body
Der Request Body beschreibt die Daten, die der Client bei POST, PUT oder PATCH senden muss. Er referenziert meist ein Schema und kann mehrere Content-Types wie application/json oder application/xml unterstützen.
Responses
Responses definieren die möglichen Antworten einer Operation. Jeder Statuscode wird mit Beschreibung, Content-Type und Schema beschrieben. Auch Fehlerantworten wie 400 oder 404 sollten vollständig dokumentiert sein.
Security Schemas
Security Schemas beschreiben, wie die API abgesichert ist. Typische Verfahren sind HTTP Basic, Bearer Token, OAuth2 und API Keys. Die Schemas werden in den Components definiert und in den Operationen referenziert.
Swagger UI und Redoc
Swagger UI und Redoc sind Tools, die aus einer OpenAPI-Spezifikation eine interaktive HTML-Dokumentation erzeugen. Swagger UI erlaubt das direkte Ausprobieren von Endpunkten im Browser, Redoc legt besonderen Wert auf ansprechende Darstellung und Lesbarkeit.
Codegenerierung
OpenAPI Generator erzeugt Client- und Server-Code aus der Spezifikation. Das beschleunigt die Entwicklung, reduziert Fehler und sorgt dafür, dass Client und Server auf demselben Vertrag basieren. Viele Programmiersprachen und Frameworks werden unterstützt.
Praxisbeispiel
Ein Shop definiert seine Bestell-API mit OpenAPI:
openapi: 3.0.3
info:
title: Shop API
version: 1.0.0
description: API für die Verwaltung von Bestellungen
servers:
- url: https://api.shop.example.com/v1
paths:
/orders:
post:
summary: Bestellung anlegen
tags:
- Orders
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/OrderRequest'
responses:
'201':
description: Bestellung erstellt
content:
application/json:
schema:
$ref: '#/components/schemas/Order'
'400':
description: Ungültige Eingabe
components:
schemas:
OrderRequest:
type: object
required:
- customerId
- items
properties:
customerId:
type: integer
example: 123
items:
type: array
items:
$ref: '#/components/schemas/OrderItem'
OrderItem:
type: object
required:
- productId
- quantity
properties:
productId:
type: integer
example: 42
quantity:
type: integer
minimum: 1
example: 2
Order:
type: object
properties:
orderId:
type: integer
example: 98765
status:
type: string
example: createdAus dieser Spezifikation kann Swagger UI eine interaktive Dokumentation generieren, OpenAPI Generator kann Clients für JavaScript, Python oder Java erzeugen und Tester können Schema-Validierungen durchführen.
FAQ: OpenAPI und Swagger
1. Was ist OpenAPI?
2. Was ist der Unterschied zwischen OpenAPI und Swagger?
3. In welchem Format wird OpenAPI geschrieben?
4. Was ist Swagger UI?
5. Was ist Redoc?
6. Was sind Components in OpenAPI?
7. Was ist Codegenerierung mit OpenAPI?
8. Was ist ein Schema in OpenAPI?
9. Was sind Security Schemas?
10. Was ist ein Single Source of Truth?
11. Was ist API First Design?
12. Was ist ein Mock-Server aus OpenAPI?
13. Was ist der Vorteil von OpenAPI für Tester?
14. Was ist OpenAPI Linting?
15. Was sind Best Practices für OpenAPI Spezifikationen?
Quellen
Buchempfehlungen zur API-Entwicklung
Wenn Du Dich weiter mit OpenAPI, API-Dokumentation und API-Design beschäftigen möchtest, empfehlen wir Dir die folgenden Bücher:
Keine Bücher für Kategorie "api-development" gefunden.