Nginx反向代理FastAPI文档接口报OpenAPI版本无效错误

这个报错和你在FastAPI初始化时传的version参数没有任何关系——这个参数是你自定义的业务API版本号，属于OpenAPI规范里info对象下的字段，不是Swagger UI校验要求的顶层OpenAPI版本声明。FastAPI本身会自动在生成的schema里加上符合要求的顶层openapi: 3.x.x字段，不需要手动配置。

问题本质是Nginx转发规则缺项：
FastAPI的/docs是Swagger UI的静态入口页，页面加载后会自动请求同域名下的/openapi.json接口拿到完整接口定义，Swagger UI就是从这个JSON文件里读取OpenAPI版本、接口路径、参数等信息做渲染的。
你现在的Nginx配置只写了/docs和/static/两个路径的转发规则，没有处理/openapi.json的请求，访问localhost:80/openapi.json时请求根本不会打到后端FastAPI服务，大概率会返回前端静态目录的404页面或者其他非JSON内容，Swagger UI拿到无效内容解析不到合法的版本字段，就会抛出你看到的错误。

另外你当前写的/docs转发规则没有处理末尾斜杠，容易出现路径拼接错误导致页面静态资源加载失败，也需要一并调整。

1. 修改Nginx配置，补全OpenAPI schema的转发规则，同时修正/docs路径的斜杠配置，参考如下：

upstream api {
  server api:8020;
}

server {
    listen 80;
    charset utf-8;
    server_name  localhost;

    root   /usr/share/nginx/html/ai-ocr;
    index  index.html index.htm;
    include /etc/nginx/extra-conf.d/*.conf;

    gzip on;
    gzip_types text/css text/javascript application/x-javascript application/json;

    # 核心：补全openapi.json的转发，解决版本字段报错
    location /openapi.json {
        proxy_redirect off;
        proxy_pass http://api/openapi.json;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header Host $http_host;
    }

    # 调整docs路径，末尾加斜杠避免路径拼接问题
    location /docs/ {
        proxy_redirect off;
        proxy_pass http://api/docs/;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header Host $http_host;
    }

    # 如果需要使用ReDoc文档，可以补充对应规则
    # location /redoc/ {
    #     proxy_redirect off;
    #     proxy_pass http://api/redoc/;
    #     proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
    #     proxy_set_header Host $http_host;
    # }

    location /static/ {
        proxy_pass http://api;
    }
}

2. 保存配置后执行nginx -s reload重载Nginx规则。
3. 验证：先直接访问http://localhost/openapi.json，如果能返回带"openapi": "3.0.x"（x为具体小版本号）字段的JSON内容，再访问http://localhost/docs就能正常渲染接口文档了。

内容的提问来源于stack exchange，提问作者CFD