OpenAPI是否规定基础空路径（如/v1/）的返回内容标准？

OpenAPI规范本身没有强制规定未声明的"空路径"（比如示例中的https://api.example.com/v1/）的返回内容，这类路径的处理逻辑由API开发者或团队的设计规范决定。

常见的实践方案有以下几种：

• 返回404 Not Found：如果该路径未对应任何实际资源，这种处理符合REST语义中"资源不存在"的定义，是最直接的选择。
• 返回API元数据：返回当前版本下的可用端点列表、API版本信息或使用说明（比如{"version": "v1", "available_endpoints": ["/users", "/organizations"]}），能为调用者提供更友好的引导。
• 重定向（3xx状态码）：将请求重定向到API文档页面或某个常用端点，但需注意这种方式是否符合REST无状态的设计原则。

如果需要标准化这个空路径的行为，可以在OpenAPI规范中显式定义该路径，示例如下：

paths:
  /v1/:
    get:
      summary: 获取v1版本API的根信息
      responses:
        '200':
          description: 成功返回API元数据
          content:
            application/json:
              schema:
                type: object
                properties:
                  version:
                    type: string
                    example: "v1"
                  available_endpoints:
                    type: array
                    items:
                      type: string
                      example: "/users"
        '404':
          description: 该路径未提供服务

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