如何使swagger post参数具有默认请求示例

Swagger（现称为OpenAPI规范）是一种用于描述、生成、消费和可视化RESTful网络服务的开放标准。在Swagger中，你可以为POST请求参数设置默认请求示例，以便其他开发者或API消费者能够理解如何构造请求。

基础概念

OpenAPI规范：定义了一种用于描述API的语言，支持OpenAPI规范的工具可以根据这些描述自动生成客户端代码、服务器存根和文档。
Swagger UI：一个基于Web的工具，可以读取OpenAPI规范并呈现交互式的API文档。

设置默认请求示例的优势

提供清晰的请求格式示例，减少API消费者的学习成本。
加速API的集成和测试过程。
提高API文档的可读性和易用性。

类型

在Swagger中，你可以通过多种方式为POST参数设置默认请求示例：

使用example字段：在参数定义中直接使用example字段来提供一个示例值。
使用x-example扩展：某些工具支持使用x-example作为非标准的扩展字段来提供示例。
使用请求体（requestBody）中的content字段：对于复杂的请求体，可以在content字段下的媒体类型（如application/json）中使用example或examples字段。

应用场景

当你希望为API的POST请求提供清晰的输入示例时，可以使用上述方法。这对于RESTful API的设计和维护尤其重要。

示例代码

以下是一个使用OpenAPI规范的YAML示例，展示了如何为一个POST请求设置默认请求示例：

openapi: 3.0.0
info:
  title: Sample API
  version: 1.0.0
paths:
  /sample:
    post:
      summary: A sample POST request
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                name:
                  type: string
                  example: John Doe
                age:
                  type: integer
                  example: 30
            examples:
              default:
                value:
                  name: Jane Smith
                  age: 25
      responses:
        '200':
          description: A successful response

在这个例子中，name和age字段都有默认的示例值。同时，在examples字段中提供了一个名为default的示例。