Java Academy Logo

Java Academy

API Documentation with OpenAPI & Swagger

Well-documented APIs are essential for team collaboration and external integrations. OpenAPI (formerly Swagger) is the industry standard for describing REST APIs.

SpringDoc OpenAPI Setup

// build.gradle
implementation 'org.springdoc:springdoc-openapi-starter-webmvc-ui:2.5.0'

// Access docs at: http://localhost:8080/swagger-ui.html

@Operation(summary = "Get customer by ID")
@ApiResponses({
    @ApiResponse(responseCode = "200", description = "Customer found"),
    @ApiResponse(responseCode = "404", description = "Customer not found")
})
@GetMapping("/{id}")
public CustomerDto get(@PathVariable Long id) { ... }

Documentation Best Practices

  • Document every endpoint with summary and description.
  • Include request/response examples.
  • Document error responses (400, 401, 404, 500).
  • Version your API in the URL (/api/v1/).
  • Keep documentation in sync with code using annotations.

Frequently Asked Questions

Swagger vs OpenAPI?▼

OpenAPI is the specification name (formerly Swagger Specification). Swagger UI is a tool that renders OpenAPI docs interactively.

Continue Learning