掌握Swagger实现跨域请求的技巧与配置方法让前后端分离项目中的API调用不再受同源策略限制轻松解决跨域访问问题

威震华夏关云长

引言

在现代Web开发中，前后端分离架构已成为主流。这种架构模式下，前端和后端分别独立开发，通过API进行数据交互。然而，这种架构也带来了一个常见的技术挑战——跨域请求问题。当前端应用与后端API不在同一个域、端口或协议下时，浏览器的同源策略会阻止前端直接访问后端API，导致请求失败。

Swagger作为一个强大的API开发工具，不仅可以帮助我们设计和文档化API，还可以通过适当的配置解决跨域请求问题。本文将详细介绍如何利用Swagger实现跨域请求，让前后端分离项目中的API调用不再受同源策略限制，轻松解决跨域访问问题。

跨域请求与同源策略基础

什么是同源策略

同源策略（Same-Origin Policy）是Web浏览器的一种重要安全机制，它规定了一个源的文档或脚本如何能与另一个源的资源进行交互。所谓”同源”或”同站点”指的是三个相同的部分：协议（protocol）、域名（domain）和端口（port）。

例如，以下URL被视为不同源：

• http://example.com/app1和http://example.com/app2（同源）
• http://example.com/app1和https://example.com/app2（不同源，协议不同）
• http://example.com/app1和http://api.example.com/app2（不同源，域名不同）
• http://example.com:8080/app1和http://example.com:8081/app2（不同源，端口不同）

跨域请求的问题

当浏览器中的JavaScript代码尝试访问不同源的资源时，就会触发同源策略的限制。对于AJAX请求，这意味着：

1. 请求会成功发送到服务器
2. 服务器会处理请求并返回响应
3. 浏览器会拦截响应，不让JavaScript代码访问返回的数据

这种限制对于保护用户数据安全非常重要，但在前后端分离的开发模式中，它常常成为开发的障碍。

Swagger简介及其在API开发中的作用

Swagger是什么

Swagger（现为OpenAPI规范）是一套围绕OpenAPI规范构建的开源工具，用于设计、构建、记录和使用RESTful Web服务。它主要包括：

• Swagger Editor：一个基于浏览器的编辑器，用于编写OpenAPI规范。
• Swagger UI：一个交互式的API文档UI，可以可视化API资源并执行API调用。
• Swagger Codegen：一个代码生成工具，可以根据OpenAPI规范生成服务器存根和客户端SDK。

Swagger在API开发中的作用

Swagger在API开发中扮演着多重角色：

1. API设计工具：帮助开发者在编码前设计API接口。
2. 交互式文档：自动生成可交互的API文档，方便前端开发者了解和使用API。
3. API测试工具：提供直接在浏览器中测试API的功能。
4. 客户端代码生成：可以根据API定义生成各种语言的客户端代码。

在前后端分离项目中，Swagger UI通常部署在后端服务器上，而前端应用则部署在另一个域或端口上，这就产生了跨域访问的问题。

跨域问题的常见解决方案

在介绍如何使用Swagger解决跨域问题之前，我们先了解一下常见的跨域解决方案：

1. JSONP（JSON with Padding）

JSONP是一种利用<script>标签不受同源策略限制的特性来实现跨域通信的方法。但JSONP只支持GET请求，且存在安全风险，现在已经不是推荐的解决方案。

2. 代理服务器

通过在同源下设置一个代理服务器，将前端的请求转发到目标服务器。这种方法在开发环境中常用，但在生产环境中会增加服务器的负担。

3. CORS（Cross-Origin Resource Sharing）

CORS是W3C推荐的一种跨域解决方案，它通过在HTTP响应头中添加特定字段来告诉浏览器允许哪些域的网页访问资源。这是目前最标准和安全的跨域解决方案。

4. WebSocket

WebSocket是一种通信协议，它不受同源策略的限制。但WebSocket主要用于实时通信，不适合普通的API请求。

5. postMessage

window.postMessage()方法允许来自不同源的脚本采用异步方式进行有限的通信。但它主要用于窗口间的通信，不适合API请求。

在以上解决方案中，CORS是最标准和安全的方法，也是我们将重点讨论的解决方案。

使用Swagger配置跨域请求的详细方法

Swagger本身并不直接处理跨域问题，但我们可以通过配置后端服务器和Swagger来支持跨域请求。下面，我将介绍几种常见框架中配置Swagger支持跨域请求的方法。

基于Spring Boot的配置

Spring Boot是Java生态中最流行的框架之一，下面介绍如何在Spring Boot项目中配置Swagger支持跨域请求。

首先，确保你的项目中包含Swagger和CORS相关的依赖：

2. <!-- Spring Boot Starter Web -->
3. <dependency>
4.     <groupId>org.springframework.boot</groupId>
5.     <artifactId>spring-boot-starter-web</artifactId>
6. </dependency>
8. <!-- Springfox Swagger2 -->
9. <dependency>
10.     <groupId>io.springfox</groupId>
11.     <artifactId>springfox-swagger2</artifactId>
12.     <version>3.0.0</version>
13. </dependency>
15. <!-- Springfox Swagger UI -->
16. <dependency>
17.     <groupId>io.springfox</groupId>
18.     <artifactId>springfox-swagger-ui</artifactId>
19.     <version>3.0.0</version>
20. </dependency>
22. <!-- Spring Boot Starter Actuator (可选，用于监控) -->
23. <dependency>
24.     <groupId>org.springframework.boot</groupId>
25.     <artifactId>spring-boot-starter-actuator</artifactId>
26. </dependency>

复制代码

创建一个Swagger配置类：

2. import org.springframework.context.annotation.Bean;
3. import org.springframework.context.annotation.Configuration;
4. import springfox.documentation.builders.ApiInfoBuilder;
5. import springfox.documentation.builders.PathSelectors;
6. import springfox.documentation.builders.RequestHandlerSelectors;
7. import springfox.documentation.service.ApiInfo;
8. import springfox.documentation.service.Contact;
9. import springfox.documentation.spi.DocumentationType;
10. import springfox.documentation.spring.web.plugins.Docket;
11. import springfox.documentation.swagger2.annotations.EnableSwagger2;
13. @Configuration
14. @EnableSwagger2
15. public class SwaggerConfig {
17.     @Bean
18.     public Docket api() {
19.         return new Docket(DocumentationType.SWAGGER_2)
20.                 .select()
21.                 .apis(RequestHandlerSelectors.basePackage("com.example.demo.controller"))
22.                 .paths(PathSelectors.any())
23.                 .build()
24.                 .apiInfo(apiInfo());
25.     }
27.     private ApiInfo apiInfo() {
28.         return new ApiInfoBuilder()
29.                 .title("API文档")
30.                 .description("API文档描述")
31.                 .version("1.0")
32.                 .contact(new Contact("作者名", "作者网址", "作者邮箱"))
33.                 .build();
34.     }
35. }

复制代码

在Spring Boot中，有多种方式配置CORS：

方法一：使用@CrossOrigin注解

可以在Controller类或具体的方法上添加@CrossOrigin注解：

2. import org.springframework.web.bind.annotation.CrossOrigin;
3. import org.springframework.web.bind.annotation.GetMapping;
4. import org.springframework.web.bind.annotation.RequestMapping;
5. import org.springframework.web.bind.annotation.RestController;
7. @RestController
8. @RequestMapping("/api")
9. @CrossOrigin(origins = "http://localhost:3000") // 允许特定源
10. public class ApiController {
12.     @GetMapping("/data")
13.     public String getData() {
14.         return "Hello, World!";
15.     }
16. }

复制代码

方法二：全局CORS配置

创建一个配置类，全局配置CORS：

2. import org.springframework.context.annotation.Bean;
3. import org.springframework.context.annotation.Configuration;
4. import org.springframework.web.cors.CorsConfiguration;
5. import org.springframework.web.cors.UrlBasedCorsConfigurationSource;
6. import org.springframework.web.filter.CorsFilter;
8. @Configuration
9. public class CorsConfig {
11.     @Bean
12.     public CorsFilter corsFilter() {
13.         UrlBasedCorsConfigurationSource source = new UrlBasedCorsConfigurationSource();
14.         CorsConfiguration config = new CorsConfiguration();
15.         config.setAllowCredentials(true); // 允许发送Cookie信息
16.         config.addAllowedOrigin("http://localhost:3000"); // 允许前端域名
17.         config.addAllowedHeader("*"); // 允许任何头
18.         config.addAllowedMethod("*"); // 允许任何方法（GET、POST等）
19.         source.registerCorsConfiguration("/**", config);
20.         return new CorsFilter(source);
21.     }
22. }

复制代码

方法三：实现WebMvcConfigurer接口

2. import org.springframework.context.annotation.Configuration;
3. import org.springframework.web.servlet.config.annotation.CorsRegistry;
4. import org.springframework.web.servlet.config.annotation.WebMvcConfigurer;
6. @Configuration
7. public class WebMvcConfig implements WebMvcConfigurer {
9.     @Override
10.     public void addCorsMappings(CorsRegistry registry) {
11.         registry.addMapping("/**")
12.                 .allowedOrigins("http://localhost:3000")
13.                 .allowedMethods("GET", "POST", "PUT", "DELETE", "OPTIONS")
14.                 .allowedHeaders("*")
15.                 .allowCredentials(true)
16.                 .maxAge(3600);
17.     }
18. }

复制代码

为了让Swagger UI能够跨域访问API，我们需要在Swagger配置中添加额外的设置：

2. import org.springframework.context.annotation.Bean;
3. import org.springframework.context.annotation.Configuration;
4. import org.springframework.web.servlet.config.annotation.ResourceHandlerRegistry;
5. import org.springframework.web.servlet.config.annotation.WebMvcConfigurer;
6. import springfox.documentation.builders.ApiInfoBuilder;
7. import springfox.documentation.builders.PathSelectors;
8. import springfox.documentation.builders.RequestHandlerSelectors;
9. import springfox.documentation.service.ApiInfo;
10. import springfox.documentation.service.Contact;
11. import springfox.documentation.spi.DocumentationType;
12. import springfox.documentation.spring.web.plugins.Docket;
13. import springfox.documentation.swagger2.annotations.EnableSwagger2;
15. @Configuration
16. @EnableSwagger2
17. public class SwaggerConfig implements WebMvcConfigurer {
19.     @Bean
20.     public Docket api() {
21.         return new Docket(DocumentationType.SWAGGER_2)
22.                 .select()
23.                 .apis(RequestHandlerSelectors.basePackage("com.example.demo.controller"))
24.                 .paths(PathSelectors.any())
25.                 .build()
26.                 .apiInfo(apiInfo());
27.     }
29.     private ApiInfo apiInfo() {
30.         return new ApiInfoBuilder()
31.                 .title("API文档")
32.                 .description("API文档描述")
33.                 .version("1.0")
34.                 .contact(new Contact("作者名", "作者网址", "作者邮箱"))
35.                 .build();
36.     }
38.     @Override
39.     public void addResourceHandlers(ResourceHandlerRegistry registry) {
40.         registry.addResourceHandler("swagger-ui.html")
41.                 .addResourceLocations("classpath:/META-INF/resources/");
42.         registry.addResourceHandler("/webjars/**")
43.                 .addResourceLocations("classpath:/META-INF/resources/webjars/");
44.     }
45. }

复制代码

下面是一个完整的Spring Boot项目示例，展示如何配置Swagger和CORS：

2. // 主应用类
3. package com.example.demo;
5. import org.springframework.boot.SpringApplication;
6. import org.springframework.boot.autoconfigure.SpringBootApplication;
8. @SpringBootApplication
9. public class DemoApplication {
10.     public static void main(String[] args) {
11.         SpringApplication.run(DemoApplication.class, args);
12.     }
13. }

复制代码

2. // Swagger配置类
3. package com.example.demo.config;
5. import org.springframework.context.annotation.Bean;
6. import org.springframework.context.annotation.Configuration;
7. import org.springframework.web.servlet.config.annotation.ResourceHandlerRegistry;
8. import org.springframework.web.servlet.config.annotation.WebMvcConfigurer;
9. import springfox.documentation.builders.ApiInfoBuilder;
10. import springfox.documentation.builders.PathSelectors;
11. import springfox.documentation.builders.RequestHandlerSelectors;
12. import springfox.documentation.service.ApiInfo;
13. import springfox.documentation.service.Contact;
14. import springfox.documentation.spi.DocumentationType;
15. import springfox.documentation.spring.web.plugins.Docket;
16. import springfox.documentation.swagger2.annotations.EnableSwagger2;
18. @Configuration
19. @EnableSwagger2
20. public class SwaggerConfig implements WebMvcConfigurer {
22.     @Bean
23.     public Docket api() {
24.         return new Docket(DocumentationType.SWAGGER_2)
25.                 .select()
26.                 .apis(RequestHandlerSelectors.basePackage("com.example.demo.controller"))
27.                 .paths(PathSelectors.any())
28.                 .build()
29.                 .apiInfo(apiInfo());
30.     }
32.     private ApiInfo apiInfo() {
33.         return new ApiInfoBuilder()
34.                 .title("API文档")
35.                 .description("API文档描述")
36.                 .version("1.0")
37.                 .contact(new Contact("作者名", "作者网址", "作者邮箱"))
38.                 .build();
39.     }
41.     @Override
42.     public void addResourceHandlers(ResourceHandlerRegistry registry) {
43.         registry.addResourceHandler("swagger-ui.html")
44.                 .addResourceLocations("classpath:/META-INF/resources/");
45.         registry.addResourceHandler("/webjars/**")
46.                 .addResourceLocations("classpath:/META-INF/resources/webjars/");
47.     }
48. }

复制代码

2. // CORS配置类
3. package com.example.demo.config;
5. import org.springframework.context.annotation.Bean;
6. import org.springframework.context.annotation.Configuration;
7. import org.springframework.web.cors.CorsConfiguration;
8. import org.springframework.web.cors.UrlBasedCorsConfigurationSource;
9. import org.springframework.web.filter.CorsFilter;
11. @Configuration
12. public class CorsConfig {
14.     @Bean
15.     public CorsFilter corsFilter() {
16.         UrlBasedCorsConfigurationSource source = new UrlBasedCorsConfigurationSource();
17.         CorsConfiguration config = new CorsConfiguration();
18.         config.setAllowCredentials(true); // 允许发送Cookie信息
19.         config.addAllowedOrigin("http://localhost:3000"); // 允许前端域名
20.         config.addAllowedHeader("*"); // 允许任何头
21.         config.addAllowedMethod("*"); // 允许任何方法（GET、POST等）
22.         source.registerCorsConfiguration("/**", config);
23.         return new CorsFilter(source);
24.     }
25. }

复制代码

2. // 示例Controller
3. package com.example.demo.controller;
5. import io.swagger.annotations.Api;
6. import io.swagger.annotations.ApiOperation;
7. import org.springframework.web.bind.annotation.GetMapping;
8. import org.springframework.web.bind.annotation.RequestMapping;
9. import org.springframework.web.bind.annotation.RestController;
11. @RestController
12. @RequestMapping("/api")
13. @Api(tags = "示例API")
14. public class ApiController {
16.     @GetMapping("/hello")
17.     @ApiOperation("获取问候语")
18.     public String sayHello() {
19.         return "Hello, World!";
20.     }
22.     @GetMapping("/data")
23.     @ApiOperation("获取数据")
24.     public Object getData() {
25.         return new Object() {
26.             public String name = "示例数据";
27.             public int value = 100;
28.         };
29.     }
30. }

复制代码

基于Node.js和Express的配置

如果你使用Node.js和Express框架，下面是如何配置Swagger和CORS的示例：

2. npm install express cors swagger-jsdoc swagger-ui-express

复制代码

2. const express = require('express');
3. const cors = require('cors');
4. const swaggerJsdoc = require('swagger-jsdoc');
5. const swaggerUi = require('swagger-ui-express');
7. const app = express();
9. // 配置CORS
10. app.use(cors({
11.     origin: 'http://localhost:3000', // 允许的前端域名
12.     methods: ['GET', 'POST', 'PUT', 'DELETE', 'OPTIONS'],
13.     allowedHeaders: ['Content-Type', 'Authorization'],
14.     credentials: true
15. }));
17. // 解析JSON请求体
18. app.use(express.json());
20. // Swagger配置
21. const options = {
22.     definition: {
23.         openapi: '3.0.0',
24.         info: {
25.             title: 'API文档',
26.             version: '1.0.0',
27.             description: 'API文档描述'
28.         },
29.         servers: [
30.             {
31.                 url: 'http://localhost:8080',
32.                 description: '开发服务器'
33.             }
34.         ]
35.     },
36.     apis: ['./routes/*.js'] // 包含API注解的文件路径
37. };
39. const specs = swaggerJsdoc(options);
40. app.use('/api-docs', swaggerUi.serve, swaggerUi.setup(specs));
42. // 示例路由
43. app.get('/api/hello', (req, res) => {
44.     /**
45.      * @swagger
46.      * /api/hello:
47.      *   get:
48.      *     summary: 获取问候语
49.      *     responses:
50.      *       200:
51.      *         description: 成功响应
52.      */
53.     res.json({ message: 'Hello, World!' });
54. });
56. app.get('/api/data', (req, res) => {
57.     /**
58.      * @swagger
59.      * /api/data:
60.      *   get:
61.      *     summary: 获取数据
62.      *     responses:
63.      *       200:
64.      *         description: 成功响应
65.      *         content:
66.      *           application/json:
67.      *             schema:
68.      *               type: object
69.      *               properties:
70.      *                 name:
71.      *                   type: string
72.      *                 value:
73.      *                   type: integer
74.      */
75.     res.json({ name: '示例数据', value: 100 });
76. });
78. const PORT = process.env.PORT || 8080;
79. app.listen(PORT, () => {
80.     console.log(`服务器运行在端口 ${PORT}`);
81.     console.log(`Swagger文档地址: http://localhost:${PORT}/api-docs`);
82. });

复制代码

基于Django REST framework的配置

对于Python的Django框架，配置Swagger和CORS的方法如下：

2. pip install django django-rest-framework django-cors-headers drf-yasg

复制代码

在settings.py中添加必要的配置：

2. # settings.py
4. INSTALLED_APPS = [
5.     # ...
6.     'rest_framework',
7.     'corsheaders',
8.     'drf_yasg',
9.     # ...
10. ]
12. # 添加CORS中间件
13. MIDDLEWARE = [
14.     'corsheaders.middleware.CorsMiddleware',  # 应该尽可能放在顶部
15.     # ...
16. ]
18. # CORS配置
19. CORS_ALLOWED_ORIGINS = [
20.     "http://localhost:3000",
21.     "http://127.0.0.1:3000",
22. ]
24. CORS_ALLOW_CREDENTIALS = True
26. # Swagger配置
27. SWAGGER_SETTINGS = {
28.     'SECURITY_DEFINITIONS': {
29.         'Basic': {
30.             'type': 'basic'
31.         },
32.         'Bearer': {
33.             'type': 'apiKey',
34.             'name': 'Authorization',
35.             'in': 'header'
36.         }
37.     }
38. }

复制代码

在urls.py中添加Swagger UI的URL：

2. # urls.py
4. from django.urls import path, include
5. from rest_framework import permissions
6. from drf_yasg.views import get_schema_view
7. from drf_yasg import openapi
9. schema_view = get_schema_view(
10.     openapi.Info(
11.         title="API文档",
12.         default_version='v1',
13.         description="API文档描述",
14.     ),
15.     public=True,
16.     permission_classes=(permissions.AllowAny,),
17. )
19. urlpatterns = [
20.     path('swagger/', schema_view.with_ui('swagger', cache_timeout=0), name='schema-swagger-ui'),
21.     path('redoc/', schema_view.with_ui('redoc', cache_timeout=0), name='schema-redoc'),
22.     path('api/', include('api.urls')),
23. ]

复制代码

2. # api/views.py
4. from rest_framework.decorators import api_view
5. from rest_framework.response import Response
6. from drf_yasg.utils import swagger_auto_schema
8. @swagger_auto_schema(
9.     method='get',
10.     operation_description='获取问候语',
11.     responses={200: '成功响应'}
12. )
13. @api_view(['GET'])
14. def hello(request):
15.     return Response({'message': 'Hello, World!'})
17. @swagger_auto_schema(
18.     method='get',
19.     operation_description='获取数据',
20.     responses={200: '成功响应'}
21. )
22. @api_view(['GET'])
23. def get_data(request):
24.     return Response({'name': '示例数据', 'value': 100})

复制代码

2. # api/urls.py
4. from django.urls import path
5. from . import views
7. urlpatterns = [
8.     path('hello/', views.hello),
9.     path('data/', views.get_data),
10. ]

复制代码

实际案例分析

让我们通过一个实际的前后端分离项目案例，来展示如何使用Swagger解决跨域问题。

项目背景

假设我们正在开发一个博客系统，前端使用React（运行在http://localhost:3000），后端使用Spring Boot（运行在http://localhost:8080）。前端需要调用后端的API来获取文章列表、文章详情等数据。

后端配置

2. <dependencies>
3.     <!-- Spring Boot Starter Web -->
4.     <dependency>
5.         <groupId>org.springframework.boot</groupId>
6.         <artifactId>spring-boot-starter-web</artifactId>
7.     </dependency>
9.     <!-- Springfox Swagger2 -->
10.     <dependency>
11.         <groupId>io.springfox</groupId>
12.         <artifactId>springfox-swagger2</artifactId>
13.         <version>3.0.0</version>
14.     </dependency>
16.     <!-- Springfox Swagger UI -->
17.     <dependency>
18.         <groupId>io.springfox</groupId>
19.         <artifactId>springfox-swagger-ui</artifactId>
20.         <version>3.0.0</version>
21.     </dependency>
23.     <!-- Spring Data JPA -->
24.     <dependency>
25.         <groupId>org.springframework.boot</groupId>
26.         <artifactId>spring-boot-starter-data-jpa</artifactId>
27.     </dependency>
29.     <!-- H2 Database -->
30.     <dependency>
31.         <groupId>com.h2database</groupId>
32.         <artifactId>h2</artifactId>
33.         <scope>runtime</scope>
34.     </dependency>
35. </dependencies>

复制代码

2. package com.example.blog.config;
4. import org.springframework.context.annotation.Bean;
5. import org.springframework.context.annotation.Configuration;
6. import org.springframework.web.servlet.config.annotation.CorsRegistry;
7. import org.springframework.web.servlet.config.annotation.ResourceHandlerRegistry;
8. import org.springframework.web.servlet.config.annotation.WebMvcConfigurer;
9. import springfox.documentation.builders.ApiInfoBuilder;
10. import springfox.documentation.builders.PathSelectors;
11. import springfox.documentation.builders.RequestHandlerSelectors;
12. import springfox.documentation.service.ApiInfo;
13. import springfox.documentation.service.Contact;
14. import springfox.documentation.spi.DocumentationType;
15. import springfox.documentation.spring.web.plugins.Docket;
16. import springfox.documentation.swagger2.annotations.EnableSwagger2;
18. @Configuration
19. @EnableSwagger2
20. public class WebConfig implements WebMvcConfigurer {
22.     @Bean
23.     public Docket api() {
24.         return new Docket(DocumentationType.SWAGGER_2)
25.                 .select()
26.                 .apis(RequestHandlerSelectors.basePackage("com.example.blog.controller"))
27.                 .paths(PathSelectors.any())
28.                 .build()
29.                 .apiInfo(apiInfo());
30.     }
32.     private ApiInfo apiInfo() {
33.         return new ApiInfoBuilder()
34.                 .title("博客系统API")
35.                 .description("博客系统的API文档")
36.                 .version("1.0")
37.                 .contact(new Contact("开发团队", "https://example.com", "team@example.com"))
38.                 .build();
39.     }
41.     @Override
42.     public void addResourceHandlers(ResourceHandlerRegistry registry) {
43.         registry.addResourceHandler("swagger-ui.html")
44.                 .addResourceLocations("classpath:/META-INF/resources/");
45.         registry.addResourceHandler("/webjars/**")
46.                 .addResourceLocations("classpath:/META-INF/resources/webjars/");
47.     }
49.     @Override
50.     public void addCorsMappings(CorsRegistry registry) {
51.         registry.addMapping("/**")
52.                 .allowedOrigins("http://localhost:3000")
53.                 .allowedMethods("GET", "POST", "PUT", "DELETE", "OPTIONS")
54.                 .allowedHeaders("*")
55.                 .allowCredentials(true)
56.                 .maxAge(3600);
57.     }
58. }

复制代码

2. package com.example.blog.entity;
4. import javax.persistence.*;
5. import java.time.LocalDateTime;
7. @Entity
8. @Table(name = "posts")
9. public class Post {
10.     @Id
11.     @GeneratedValue(strategy = GenerationType.IDENTITY)
12.     private Long id;
14.     @Column(nullable = false)
15.     private String title;
17.     @Column(nullable = false, columnDefinition = "TEXT")
18.     private String content;
20.     @Column(name = "created_at")
21.     private LocalDateTime createdAt;
23.     @Column(name = "updated_at")
24.     private LocalDateTime updatedAt;
26.     // 构造函数、getter和setter
27.     public Post() {
28.         this.createdAt = LocalDateTime.now();
29.         this.updatedAt = LocalDateTime.now();
30.     }
32.     public Post(String title, String content) {
33.         this();
34.         this.title = title;
35.         this.content = content;
36.     }
38.     // 省略getter和setter...
39. }

复制代码

2. package com.example.blog.repository;
4. import com.example.blog.entity.Post;
5. import org.springframework.data.jpa.repository.JpaRepository;
6. import org.springframework.stereotype.Repository;
8. @Repository
9. public interface PostRepository extends JpaRepository<Post, Long> {
10. }

复制代码

2. package com.example.blog.controller;
4. import com.example.blog.entity.Post;
5. import com.example.blog.repository.PostRepository;
6. import io.swagger.annotations.Api;
7. import io.swagger.annotations.ApiOperation;
8. import org.springframework.beans.factory.annotation.Autowired;
9. import org.springframework.http.HttpStatus;
10. import org.springframework.http.ResponseEntity;
11. import org.springframework.web.bind.annotation.*;
13. import java.util.List;
14. import java.util.Optional;
16. @RestController
17. @RequestMapping("/api/posts")
18. @Api(tags = "文章管理")
19. public class PostController {
21.     @Autowired
22.     private PostRepository postRepository;
24.     @GetMapping
25.     @ApiOperation("获取所有文章")
26.     public List<Post> getAllPosts() {
27.         return postRepository.findAll();
28.     }
30.     @GetMapping("/{id}")
31.     @ApiOperation("根据ID获取文章")
32.     public ResponseEntity<Post> getPostById(@PathVariable Long id) {
33.         Optional<Post> post = postRepository.findById(id);
34.         return post.map(ResponseEntity::ok)
35.                 .orElseGet(() -> ResponseEntity.notFound().build());
36.     }
38.     @PostMapping
39.     @ApiOperation("创建新文章")
40.     public ResponseEntity<Post> createPost(@RequestBody Post post) {
41.         Post savedPost = postRepository.save(post);
42.         return new ResponseEntity<>(savedPost, HttpStatus.CREATED);
43.     }
45.     @PutMapping("/{id}")
46.     @ApiOperation("更新文章")
47.     public ResponseEntity<Post> updatePost(@PathVariable Long id, @RequestBody Post postDetails) {
48.         return postRepository.findById(id)
49.                 .map(post -> {
50.                     post.setTitle(postDetails.getTitle());
51.                     post.setContent(postDetails.getContent());
52.                     post.setUpdatedAt(LocalDateTime.now());
53.                     Post updatedPost = postRepository.save(post);
54.                     return ResponseEntity.ok(updatedPost);
55.                 })
56.                 .orElseGet(() -> ResponseEntity.notFound().build());
57.     }
59.     @DeleteMapping("/{id}")
60.     @ApiOperation("删除文章")
61.     public ResponseEntity<Void> deletePost(@PathVariable Long id) {
62.         return postRepository.findById(id)
63.                 .map(post -> {
64.                     postRepository.delete(post);
65.                     return ResponseEntity.ok().<Void>build();
66.                 })
67.                 .orElseGet(() -> ResponseEntity.notFound().build());
68.     }
69. }

复制代码

前端配置

2. npx create-react-app blog-frontend
3. cd blog-frontend
4. npm install axios

复制代码

2. // src/services/api.js
4. import axios from 'axios';
6. const api = axios.create({
7.     baseURL: 'http://localhost:8080/api',
8.     timeout: 10000,
9.     headers: {
10.         'Content-Type': 'application/json'
11.     }
12. });
14. export default api;

复制代码

2. // src/services/postService.js
4. import api from './api';
6. export const getAllPosts = () => {
7.     return api.get('/posts');
8. };
10. export const getPostById = (id) => {
11.     return api.get(`/posts/${id}`);
12. };
14. export const createPost = (post) => {
15.     return api.post('/posts', post);
16. };
18. export const updatePost = (id, post) => {
19.     return api.put(`/posts/${id}`, post);
20. };
22. export const deletePost = (id) => {
23.     return api.delete(`/posts/${id}`);
24. };

复制代码

2. // src/components/PostList.js
4. import React, { useState, useEffect } from 'react';
5. import { getAllPosts, deletePost } from '../services/postService';
6. import PostForm from './PostForm';
8. const PostList = () => {
9.     const [posts, setPosts] = useState([]);
10.     const [editingPost, setEditingPost] = useState(null);
11.     const [loading, setLoading] = useState(true);
12.     const [error, setError] = useState(null);
14.     useEffect(() => {
15.         fetchPosts();
16.     }, []);
18.     const fetchPosts = async () => {
19.         try {
20.             setLoading(true);
21.             const response = await getAllPosts();
22.             setPosts(response.data);
23.             setError(null);
24.         } catch (err) {
25.             setError('获取文章列表失败');
26.             console.error('Error fetching posts:', err);
27.         } finally {
28.             setLoading(false);
29.         }
30.     };
32.     const handleDelete = async (id) => {
33.         if (window.confirm('确定要删除这篇文章吗？')) {
34.             try {
35.                 await deletePost(id);
36.                 setPosts(posts.filter(post => post.id !== id));
37.             } catch (err) {
38.                 setError('删除文章失败');
39.                 console.error('Error deleting post:', err);
40.             }
41.         }
42.     };
44.     const handleEdit = (post) => {
45.         setEditingPost(post);
46.     };
48.     const handleFormSubmit = () => {
49.         setEditingPost(null);
50.         fetchPosts();
51.     };
53.     if (loading) return <div>加载中...</div>;
54.     if (error) return <div>{error}</div>;
56.     return (
57.         <div className="post-list">
58.             <h1>博客文章</h1>
59.             <PostForm post={editingPost} onSubmit={handleFormSubmit} />
60.             <ul>
61.                 {posts.map(post => (
62.                     <li key={post.id}>
63.                         <h2>{post.title}</h2>
64.                         <p>{post.content.substring(0, 100)}...</p>
65.                         <button onClick={() => handleEdit(post)}>编辑</button>
66.                         <button onClick={() => handleDelete(post.id)}>删除</button>
67.                     </li>
68.                 ))}
69.             </ul>
70.         </div>
71.     );
72. };
74. export default PostList;

复制代码

2. // src/components/PostForm.js
4. import React, { useState } from 'react';
5. import { createPost, updatePost } from '../services/postService';
7. const PostForm = ({ post, onSubmit }) => {
8.     const [formData, setFormData] = useState({
9.         title: post ? post.title : '',
10.         content: post ? post.content : ''
11.     });
12.     const [loading, setLoading] = useState(false);
13.     const [error, setError] = useState(null);
15.     const handleChange = (e) => {
16.         const { name, value } = e.target;
17.         setFormData(prev => ({
18.             ...prev,
19.             [name]: value
20.         }));
21.     };
23.     const handleSubmit = async (e) => {
24.         e.preventDefault();
25.         setLoading(true);
26.         setError(null);
28.         try {
29.             if (post) {
30.                 // 更新文章
31.                 await updatePost(post.id, formData);
32.             } else {
33.                 // 创建新文章
34.                 await createPost(formData);
35.             }
36.             setFormData({ title: '', content: '' });
37.             onSubmit();
38.         } catch (err) {
39.             setError(post ? '更新文章失败' : '创建文章失败');
40.             console.error('Error submitting form:', err);
41.         } finally {
42.             setLoading(false);
43.         }
44.     };
46.     return (
47.         <div className="post-form">
48.             <h2>{post ? '编辑文章' : '添加新文章'}</h2>
49.             {error && <div className="error">{error}</div>}
50.             <form onSubmit={handleSubmit}>
51.                 <div>
52.                     <label htmlFor="title">标题</label>
53.                     <input
54.                         type="text"
55.                         id="title"
56.                         name="title"
57.                         value={formData.title}
58.                         onChange={handleChange}
59.                         required
60.                     />
61.                 </div>
62.                 <div>
63.                     <label htmlFor="content">内容</label>
64.                     <textarea
65.                         id="content"
66.                         name="content"
67.                         value={formData.content}
68.                         onChange={handleChange}
69.                         required
70.                     />
71.                 </div>
72.                 <button type="submit" disabled={loading}>
73.                     {loading ? '提交中...' : (post ? '更新' : '创建')}
74.                 </button>
75.                 {post && (
76.                     <button type="button" onClick={() => onSubmit()}>
77.                         取消
78.                     </button>
79.                 )}
80.             </form>
81.         </div>
82.     );
83. };
85. export default PostForm;

复制代码

2. // src/App.js
4. import React from 'react';
5. import PostList from './components/PostList';
6. import './App.css';
8. function App() {
9.     return (
10.         <div className="App">
11.             <header className="App-header">
12.                 <h1>博客系统</h1>
13.             </header>
14.             <main>
15.                 <PostList />
16.             </main>
17.         </div>
18.     );
19. }
21. export default App;

复制代码

测试跨域请求

1. 启动后端Spring Boot应用，访问http://localhost:8080/swagger-ui.html，可以查看API文档并测试API。
2. 启动前端React应用，访问http://localhost:3000，可以查看文章列表并进行增删改查操作。

启动后端Spring Boot应用，访问http://localhost:8080/swagger-ui.html，可以查看API文档并测试API。

启动前端React应用，访问http://localhost:3000，可以查看文章列表并进行增删改查操作。

由于我们在后端配置了CORS，前端应用可以正常调用后端API，不会遇到跨域问题。

最佳实践和注意事项

在使用Swagger解决跨域请求问题时，以下是一些最佳实践和注意事项：

1. 安全性考虑

• 限制允许的源：在生产环境中，不要使用*作为允许的源，而是明确指定允许访问的前端域名。

2. // 不推荐
3.   config.addAllowedOrigin("*");
4.   
5.   // 推荐
6.   config.addAllowedOrigin("https://your-frontend-domain.com");

复制代码

• 谨慎使用allowCredentials：只有在前端确实需要发送Cookie等凭证信息时，才设置allowCredentials(true)。
• 限制HTTP方法：根据API的实际需求，只允许必要的HTTP方法。

谨慎使用allowCredentials：只有在前端确实需要发送Cookie等凭证信息时，才设置allowCredentials(true)。

限制HTTP方法：根据API的实际需求，只允许必要的HTTP方法。

2. config.addAllowedMethod("GET");
3.   config.addAllowedMethod("POST");
4.   // 而不是
5.   config.addAllowedMethod("*");

复制代码

2. 性能优化

• 缓存CORS配置：通过设置maxAge，可以让浏览器缓存CORS配置，减少预检请求的次数。

2. config.setMaxAge(3600); // 缓存1小时

复制代码

• 合理使用预检请求：对于简单的GET、POST请求（不包含自定义头和复杂内容），浏览器不会发送预检请求。设计API时，尽量遵循简单请求的原则。

3. 开发与生产环境区分

• 环境变量配置：使用环境变量来区分开发和生产环境的CORS配置。

2. @Value("${cors.allowed-origins}")
3.   private String allowedOrigins;
4.   
5.   // 在application.properties中
6.   // 开发环境: cors.allowed-origins=http://localhost:3000
7.   // 生产环境: cors.allowed-origins=https://your-frontend-domain.com

复制代码

• 多环境配置文件：在Spring Boot中，可以使用不同的配置文件来区分环境。

2. # application-dev.properties
3.   cors.allowed-origins=http://localhost:3000
4.   
5.   # application-prod.properties
6.   cors.allowed-origins=https://your-frontend-domain.com

复制代码

4. Swagger配置最佳实践

• API版本控制：在Swagger配置中添加API版本控制，方便管理不同版本的API。

2. @Bean
3.   public Docket apiV1() {
4.       return new Docket(DocumentationType.SWAGGER_2)
5.               .groupName("v1")
6.               .select()
7.               .apis(RequestHandlerSelectors.basePackage("com.example.blog.controller.v1"))
8.               .paths(PathSelectors.ant("/api/v1/**"))
9.               .build()
10.               .apiInfo(apiInfoV1());
11.   }
12.   
13.   @Bean
14.   public Docket apiV2() {
15.       return new Docket(DocumentationType.SWAGGER_2)
16.               .groupName("v2")
17.               .select()
18.               .apis(RequestHandlerSelectors.basePackage("com.example.blog.controller.v2"))
19.               .paths(PathSelectors.ant("/api/v2/**"))
20.               .build()
21.               .apiInfo(apiInfoV2());
22.   }

复制代码

• API分组：使用@Api注解对API进行分组，提高文档的可读性。

2. @RestController
3.   @RequestMapping("/api/posts")
4.   @Api(tags = "文章管理")
5.   public class PostController {
6.       // ...
7.   }

复制代码

• 详细文档：使用@ApiOperation和@ApiParam等注解提供详细的API文档。

2. @GetMapping("/{id}")
3.   @ApiOperation("根据ID获取文章")
4.   @ApiImplicitParams({
5.       @ApiImplicitParam(name = "id", value = "文章ID", required = true, dataType = "Long", paramType = "path")
6.   })
7.   public ResponseEntity<Post> getPostById(@PathVariable Long id) {
8.       // ...
9.   }

复制代码

5. 常见问题排查

• CORS错误：如果前端仍然遇到CORS错误，检查：后端CORS配置是否正确请求的URL是否正确服务器是否正确响应了预检请求（OPTIONS请求）
• 后端CORS配置是否正确
• 请求的URL是否正确
• 服务器是否正确响应了预检请求（OPTIONS请求）
• Swagger UI无法访问：如果Swagger UI无法访问，检查：是否正确添加了Swagger依赖是否正确配置了资源处理器是否有其他拦截器阻止了对Swagger UI资源的访问
• 是否正确添加了Swagger依赖
• 是否正确配置了资源处理器
• 是否有其他拦截器阻止了对Swagger UI资源的访问
• API文档不完整：如果API文档不完整或缺少某些接口，检查：是否正确使用了Swagger注解扫描的包路径是否正确是否有条件配置（如Profile）导致某些Bean未被加载
• 是否正确使用了Swagger注解
• 扫描的包路径是否正确
• 是否有条件配置（如Profile）导致某些Bean未被加载

CORS错误：如果前端仍然遇到CORS错误，检查：

• 后端CORS配置是否正确
• 请求的URL是否正确
• 服务器是否正确响应了预检请求（OPTIONS请求）

Swagger UI无法访问：如果Swagger UI无法访问，检查：

• 是否正确添加了Swagger依赖
• 是否正确配置了资源处理器
• 是否有其他拦截器阻止了对Swagger UI资源的访问

API文档不完整：如果API文档不完整或缺少某些接口，检查：

• 是否正确使用了Swagger注解
• 扫描的包路径是否正确
• 是否有条件配置（如Profile）导致某些Bean未被加载

总结

在前后端分离的项目中，跨域请求是一个常见的问题，但通过正确配置Swagger和CORS，我们可以轻松解决这个问题。本文详细介绍了如何在Spring Boot、Node.js/Express和Django框架中配置Swagger支持跨域请求，并通过一个实际的博客系统案例展示了完整的实现过程。

关键要点包括：

1. 理解同源策略和跨域请求的基本概念
2. 掌握Swagger的基本配置和使用方法
3. 学习如何在不同框架中配置CORS支持
4. 通过实际案例了解前后端分离项目的完整实现
5. 遵循最佳实践，确保API的安全性和性能

通过本文的指导，你应该能够掌握使用Swagger实现跨域请求的技巧与配置方法，让前后端分离项目中的API调用不再受同源策略限制，轻松解决跨域访问问题。这不仅提高了开发效率，也改善了开发体验，使前后端团队能够更加顺畅地协作。