Swagger — živá dokumentace REST API

Měli jsme Word dokument s popisem API. Padesát stran, dvě verze, obě zastaralé. Swagger přinesl dokumentaci generovanou z kódu, s interaktivním UI pro testování.

Code-first s SpringFox¶

@ApiOperation(value = "Seznam projektů")
@GetMapping
public List<Project> getProjects(
    @ApiParam(value = "Filtr podle stavu")
    @RequestParam(required = false) String status) {
    return projectService.findAll(status);
}

Dokumentace z kódu → vždy aktuální. Swagger UI: interaktivní testování v prohlížeči. Swagger Codegen: generování klientů pro TypeScript, Java, Python.

Best practices¶

• Popisujte každý endpoint a chybové odpovědi
• Používejte modely, ne inline definice
• Verzujte specifikaci spolu s API
• Integrujte Swagger UI do aplikace

Swagger je standard¶

V roce 2015 nemá smysl provozovat REST API bez OpenAPI specifikace.