能否在OpenAPI 3.0根级别指定默认请求/响应格式？

好问题！其实OpenAPI 3.0完全支持定义全局默认的JSON内容类型，同时允许你在需要的单个请求或响应中灵活覆盖这个默认值，帮你避免重复繁琐的配置。下面是两种常用的实现方式：

方法1：利用组件（Components）定义通用模板 #

你可以在components节点下预先定义好通用的JSON响应、请求体模板，之后在各个接口中直接引用即可。

定义全局JSON响应与请求体模板 #

openapi: 3.0.3
info:
  title: Your API
  version: 1.0.0
components:
  responses:
    DefaultJsonResponse:
      description: 成功响应
      content:
        application/json:
          schema:
            type: object
            properties:
              code:
                type: integer
              message:
                type: string
  requestBodies:
    DefaultJsonRequestBody:
      content:
        application/json:
          schema:
            type: object
paths:
  /users:
    get:
      responses:
        '200':
          $ref: '#/components/responses/DefaultJsonResponse' # 引用全局响应模板
    post:
      requestBody:
        $ref: '#/components/requestBodies/DefaultJsonRequestBody' # 引用全局请求体模板
      responses:
        '201':
          $ref: '#/components/responses/DefaultJsonResponse'

覆盖默认设置 #

如果某个接口需要返回非JSON格式（比如XML），或者需要自定义请求体类型，直接在该接口中重新定义content即可，会自动覆盖全局模板：

paths:
  /users/xml:
    get:
      responses:
        '200':
          description: 返回XML格式的用户列表
          content:
            application/xml:
              schema:
                type: object
                properties:
                  users:
                    type: array
                    items:
                      type: object

方法2：使用路径默认值（Path Defaults） #

OpenAPI 3.0允许在paths节点下定义default属性，为所有未明确指定配置的接口设置默认行为，包括默认的请求体和响应内容类型：

openapi: 3.0.3
info:
  title: Your API
  version: 1.0.0
paths:
  default:
    # 为所有接口设置默认请求体类型
    requestBody:
      content:
        application/json: {}
    # 为所有接口设置默认响应类型
    responses:
      '200':
        content:
          application/json: {}
  /users:
    get:
      # 无需重复写content，会继承default里的配置
      responses:
        '200':
          description: 获取用户列表
  /products:
    post:
      # 这里自定义请求体，覆盖默认设置
      requestBody:
        content:
          application/x-www-form-urlencoded:
            schema:
              type: object
              properties:
                name:
                  type: string
      responses:
        '201':
          description: 创建产品成功

这两种方式都能帮你减少重复代码，同时保持足够的灵活性，满足大部分场景的需求。

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