Using Swagger with Spring Boot: Setup, Configuration, and Common Issues
This tutorial explains what Swagger is, why it is useful for RESTful API documentation, and provides step‑by‑step instructions for integrating Swagger 3.0 into a Spring Boot 2.7.6 project, including Maven dependencies, configuration classes, handling startup errors, customizing the UI, security settings, and annotation usage.
Swagger is a popular tool for generating readable, interactive RESTful API documentation directly from code annotations, helping developers avoid manual doc maintenance and keeping docs in sync with API changes.
The article shows how to add Swagger 3.0 to a Spring Boot 2.7.6 project, starting with Maven dependencies for spring-boot-starter-web and springfox-boot-starter , then creating a simple TestController with a /test endpoint.
A configuration class SwaggerConfig is created and annotated with @Configuration and @EnableSwagger2 to enable Swagger support.
When starting the application, a conflict between Spring Boot’s PathPatternMatcher and Springfox’s AntPathMatcher may cause a bean initialization error; four solutions are presented: downgrade versions, set spring.mvc.pathmatch.matching-strategy=ant_path_matcher in application.yml , add @EnableWebMvc to the config, or register a custom BeanPostProcessor that filters handler mappings.
After fixing the error, the Swagger UI can be accessed at http://127.0.0.1:9002/swagger-ui/index.html , where the single /test endpoint is displayed. The guide recommends specifying request methods (e.g., @GetMapping ) to avoid redundant entries.
The article then dives into detailed Swagger customization using the Docket bean: selecting APIs and paths, setting groupName for multiple documentation groups, configuring apiInfo (title, description, version, contact, license), enabling/disabling docs per environment, defining the host, and adding security schemes such as Bearer , Authorization , and Basic headers.
Security contexts are shown to attach the defined schemes to specific endpoints, and tags are used to group APIs. Additional annotations ( @ApiIgnore , @ApiModel , @ApiModelProperty , @Api , @ApiOperation , @ApiImplicitParams , @ApiImplicitParam , @ApiParam , @ApiResponses , @ApiResponse ) are explained for fine‑grained control over what appears in the generated documentation.
Finally, the tutorial notes that while Swagger may not be a frequent interview topic, maintaining clear API documentation is a professional habit for any backend developer.
Wukong Talks Architecture
Explaining distributed systems and architecture through stories. Author of the "JVM Performance Tuning in Practice" column, open-source author of "Spring Cloud in Practice PassJava", and independently developed a PMP practice quiz mini-program.
How this landed with the community
Was this worth your time?
0 Comments
Thoughtful readers leave field notes, pushback, and hard-won operational detail here.