If your REST API documentation was written by a committee of mimes then this guide will help. You will add Swagger powered UI to a Spring Boot app so humans can click through endpoints and actually understand what your API does.

Why bother with Swagger and OpenAPI

Short answer, because API documentation that you can try without reading three README files is worth its weight in bug fixes. Swagger and OpenAPI give interactive api documentation that clients and developers can test from a browser. Use springdoc for modern Spring Boot versions unless you are forced by legacy to use springfox.

Quick setup for Maven and Gradle

Add the openapi ui dependency and you are halfway done. Example for Maven using springdoc

<dependency>
  <groupId>org.springdoc</groupId>
  <artifactId>springdoc-openapi-ui</artifactId>
  <version>1.6.14</version>
</dependency>

If you prefer Gradle use the normal coordinate form in your build file

implementation 'org.springdoc:springdoc-openapi-ui:1.6.14'

Configure basic OpenAPI settings

Set a few properties so the generated docs are not anonymous. Edit application.properties or application.yml and set the api title and version and the ui path if you like. For example using properties you can set springdoc.swagger-ui.path to control where the UI appears.

Example properties

springdoc.swagger-ui.path=/swagger-ui.html
springdoc.api-docs.path=/v3/api-docs
spring.application.name=My Awesome Service

Optional configuration class for advanced needs

When you crave more control create a @Configuration class and add an @OpenAPIDefinition bean to provide global info like contact, license and servers. You can also register GroupedOpenApi beans to split docs into logical groups. This is recommended if you have several APIs in one project.

Annotate controllers and models for clearer docs

Add @Operation to controller methods for summaries and descriptions. Use @Parameter for query or header details. On DTOs use @Schema on fields to specify types, examples and required flags so consumers stop guessing what that string actually contains.

Small checklist

• Add springdoc dependency via maven or gradle
• Configure title version and ui path in application properties
• Create a config class for openapi if you need groups or servers
• Annotate controllers with @Operation and parameters with @Parameter
• Annotate models with @Schema to improve generated types and examples

Security and testing endpoints from the UI

If your endpoints require authentication add security schemes in the OpenAPI config and mark operations accordingly. This allows consumers to authorize right from the swagger ui and test calls without raising a support ticket.

Run and view the docs

Start your Spring Boot application and open the swagger ui at paths such as /swagger-ui.html or /swagger-ui/index.html or at whatever custom path you configured. The UI will fetch the OpenAPI json from /v3/api-docs so you can inspect models endpoints and try requests directly from the browser.

Notes on tooling and migration

springdoc integrates well with modern Spring Boot. If you are using springfox that is fine for older applications but springdoc supports newer Spring versions more smoothly. Maven and Gradle are both supported without special tricks.

That is the gist. You install the dependency, configure a few properties, annotate where it helps and optionally add a config class for advanced stuff. The result is usable, clickable api documentation that does not require psychic powers to read.