<properties>
   <springfox.version>2.6.1</springfox.version>
</properties>

<dependencies>
   <dependency>
       <groupId>io.springfox</groupId>
       <artifactId>springfox-swagger2</artifactId>
       <version>${springfox.version}</version>
   </dependency>
   <dependency>
       <groupId>io.springfox</groupId>
       <artifactId>springfox-swagger-ui</artifactId>
       <version>${springfox.version}</version>
   </dependency>
</dependencies>

2. Configure Swagger via Java Configuration

package com.example.config;

import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import springfox.documentation.builders.ApiInfoBuilder;
import springfox.documentation.builders.PathSelectors;
import springfox.documentation.builders.RequestHandlerSelectors;
import springfox.documentation.service.ApiInfo;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2;

@Configuration
@EnableSwagger2
public class SwaggerConfiguration {

   @Bean
   public Docket api() {
       return new Docket(DocumentationType.SWAGGER_2)
               .select()
               .apis(RequestHandlerSelectors.basePackage("com.example.controller"))
               .paths(PathSelectors.any())
               .build()
               .apiInfo(apiInfo());
   }

   private ApiInfo apiInfo() {
       return new ApiInfoBuilder()
               .title("API Documentation")
               .description("Comprehensive REST API reference for the application.")
               .version("1.0")
               .build();
   }
}

3. Key Swagger Annotations

• @Api – Marks a controller class as a Swagger resource. Use description for clarity; avoid non-ASCII characters in tags.
• @ApiOperation – Describes an HTTP endpoint. Use value for brief title and notes for extended details.
• @ApiParam – Documents method parameters. Specify name, value, and required to clarify input expectations.
• @ApiModel – Describes a DTO or entity class used in request/response bodies.
• @ApiModelProperty – Documents individual fields within a model. Supports example, hidden, and dataType overrides.
• @ApiIgnore – Excludes a class or method from documentation.
• @ApiImplicitParam / @ApiImplicitParams – Defines parameters not directly bound to method arguments (e.g., headers, query params).

4. Accessing the UI

After starting the application, navigate to:

http://localhost:8080/your-context-path/swagger-ui.html

Replace your-context-path with your application’s configured context root.

5. Common Pitfall: Non-ASCII Characters in Tags

Using Chinese or other non-Latin characters in the tags attribute of @Api may cause the Swagger UI to fail rendering endpoints correctly. Instead, use English descriptions:

// ❌ Avoid this
@Api(tags = "登录接口", description = "用户登录功能")

// ✅ Use this
@Api(description = "User authentication endpoint")