Swagger — Lebendige Dokumentation für REST-APIs

Wir hatten ein Word-Dokument, das unsere API beschrieb. Fünfzig Seiten, zwei Versionen, beide veraltet. Swagger brachte Dokumentation, die aus dem Code generiert wird, mit einer interaktiven Oberfläche zum Testen.

Code-First mit SpringFox¶

@ApiOperation(value = "List of projects")
@GetMapping
public List<Project> getProjects(
    @ApiParam(value = "Filter by status")
    @RequestParam(required = false) String status) {
    return projectService.findAll(status);
}

Dokumentation aus Code → immer aktuell. Swagger UI: interaktives Testen im Browser. Swagger Codegen: Client-Generierung für TypeScript, Java, Python.

Best Practices¶

• Jeden Endpoint und seine Fehlerantworten beschreiben
• Modelle statt Inline-Definitionen verwenden
• Die Spezifikation zusammen mit der API versionieren
• Swagger UI in die Anwendung integrieren

Swagger ist der Standard¶

2015 gibt es keinen Grund, eine REST-API ohne OpenAPI-Spezifikation zu betreiben.