Spring Boot 使用Swagger生成API文档

原创已于 2025-12-31 17:38:15 修改 · 795 阅读

6 ·

本内容遵循CC 4.0 BY-SA版权协议

GEO检测

于 2025-12-31 17:09:47 首次发布

1. 方案一【下边有方案二，推荐使用方案二】

1.1添加Swagger依赖 --SpringDoc OpenAPI依赖

        <!-- SpringDoc OpenAPI UI (Swagger UI) -->
        <dependency>
            <groupId>org.springdoc</groupId>
            <artifactId>springdoc-openapi-ui</artifactId>
            <version>1.7.0</version>
        </dependency>

1.2 配置yml，

# ==================== Swagger配置 ====================
springdoc:
  api-docs:
    enabled: true
    path: /api-docs
  swagger-ui:
    enabled: true
    path: /swagger-ui.html
    operations-sorter: method
    tags-sorter: alpha
  packages-to-scan: com.controller  # 指定扫描的包路径

1.3 启动器编辑

@Slf4j
@SpringBootApplication
@OpenAPIDefinition(info = @Info(title = "Super MAM API"))
@MapperScan("com.mapper")
public class SpringBootApplication {

	public static void main(String[] args) throws UnknownHostException {
		ConfigurableApplicationContext application = SpringApplication.run(LaosLoadsApplication.class, args);
		Environment env = application.getEnvironment();
		String ip = InetAddress.getLocalHost().getHostAddress();
		String port = env.getProperty("server.port");
		String path = env.getProperty("server.servlet.context-path")==null?"":env.getProperty("server.servlet.context-path");
		log.info("\n----------------------------------------------------------\n\t" +
						"Application Spring-Boot is running! Access URLs:\n\t" +
						"Local: \t\thttp://localhost:" + port + path + "/\n\t" +
						"External: \thttp://" + ip + ":" + port + path + "/\n\t" +
						"Swagger-UI: \t\thttp://" + ip + ":" + port + path + "/swagger-ui.html\n" +
						"----------------------------------------------------------");
		System.out.println("启动成功！");
	}
}

右键点击 `pom.xml` → Maven → Reload Project

或者 maven clean -> compile

2.方案二

2.1 添加依赖

<dependency>
    <groupId>com.github.xiaoymin</groupId>
    <artifactId>knife4j-spring-boot-starter</artifactId>
    <version>3.0.3</version>
</dependency>

2.2 配置yml

# ==================== Knife4j配置 ====================
knife4j:
  enable: true
  production: false  # 是否开启生产环境屏蔽，true屏蔽
  basic:
    enable: false
    username: admin
    password: 123456
  setting:
    language: zh-CN  # 界面语言
    swagger-model-name: 实体类列表
    enable-version: true
    enable-footer: false
    enable-footer-custom: false

2.3 启动器edit

@Slf4j
@SpringBootApplication
@OpenAPIDefinition(info = @Info(title = "Super MAM API"))
@MapperScan("com.mapper")
public class SpringBootApplication {

   public static void main(String[] args) throws UnknownHostException {
       ConfigurableApplicationContext application = SpringApplication.run(LaosLoadsApplication.class, args);
       Environment env = application.getEnvironment();
       String ip = InetAddress.getLocalHost().getHostAddress();
       String port = env.getProperty("server.port");
       String path = env.getProperty("server.servlet.context-path")==null?"":env.getProperty("server.servlet.context-path");
       log.info("\n----------------------------------------------------------\n\t" +
                       "Application Spring-Boot is running! Access URLs:\n\t" +
                       "Local: \t\thttp://localhost:" + port + path + "/\n\t" +
                       "External: \thttp://" + ip + ":" + port + path + "/\n\t" +

"Knife4j-UI: \t\thttp://" + ip + ":" + port + path + "/doc.html\n" + "----------------------------------------------------------");
       System.out.println("启动成功！");
   }
}

右键点击 `pom.xml` → Maven → Reload Project

或者 maven clean -> compile

2.4 controller加注解

@RestController
@Tag(name = "产品管理")
@RequestMapping("/pd")
public class ProductController {
  @Autowired
  private ProductService productService;
  @GetMapping("/search")
  @Operation(summary = "返回所有产品列表", description = "返回所有产品列表")
  public ResponseEntity<Map<String, Object>> searchProductList(
      @RequestParam(required = false) String id,