Swagger — Living Documentation for REST APIs

We had a Word document describing our API. Fifty pages, two versions, both outdated. Swagger brought documentation generated from code, with an interactive UI for testing.

Code-First with 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);
}

Documentation from code → always up to date. Swagger UI: interactive testing in the browser. Swagger Codegen: client generation for TypeScript, Java, Python.

Best Practices¶

• Describe every endpoint and its error responses
• Use models rather than inline definitions
• Version the specification alongside the API
• Integrate Swagger UI into the application

Swagger Is the Standard¶

In 2015, there is no reason to run a REST API without an OpenAPI specification.