使用Swagger定义自定义入参和出参（过滤器）

Swagger是一种强大的API文档生成工具，它可以帮助开发人员更清晰地定义、描述、文档化和测试API。在Swagger中，你可以定义各种参数和响应，包括自定义的入参和出参。通过定义这些参数，你可以更好地控制API的输入和输出，并为其添加必要的过滤器。

定义自定义入参

首先，让我们看看如何定义自定义的入参。在Swagger中，入参通常定义为路径参数、查询参数、请求头或请求体。为了定义自定义的入参，你需要在Swagger的YAML或JSON配置文件中添加相应的字段。

以下是一个使用Swagger YAML定义自定义入参的示例：

paths:
  /users/{userId}:
    get:
      summary: 获取指定用户信息
      parameters:
        - name: userId
          in: path
          description: 用户ID
          required: true
          type: string
        - name: customParam
          in: query
          description: 自定义参数
          required: false
          type: string
      responses:
        200:
          description: 用户信息
          schema:
            $ref: '#/definitions/User'

在上面的示例中，我们定义了一个路径参数userId和一个查询参数customParam。customParam就是一个自定义的入参，你可以根据需要修改其名称、类型和描述。

定义自定义出参

接下来，让我们看看如何定义自定义的出参。在Swagger中，出参通常定义为API响应的组成部分。你可以通过定义响应模式（schemas）来指定出参的结构。

以下是一个使用Swagger YAML定义自定义出参的示例：

definitions:
  User:
    type: object
    properties:
      id:
        type: string
        description: 用户ID
      name:
        type: string
        description: 用户姓名
      customField:
        type: string
        description: 自定义字段

在上面的示例中，我们定义了一个名为User的响应模式，它包含了一个自定义字段customField。你可以根据需要添加或修改该字段的类型和描述。

应用过滤器

在Swagger中，过滤器通常用于限制API的可见性或访问权限。你可以使用Swagger的安全定义和授权机制来应用过滤器。

以下是一个使用Swagger YAML应用过滤器的示例：

securityDefinitions:
  api_key:
    type: apiKey
    in: header
    name: X-API-KEY
security:
  - api_key: []

在上面的示例中，我们定义了一个名为api_key的安全定义，并将其应用于所有的API。这意味着，只有提供有效API密钥的请求才能访问这些API。

通过结合自定义入参、出参和过滤器，你可以更好地管理和描述你的API，并为其添加必要的安全性和访问控制。希望这些示例和建议能帮助你更好地使用Swagger来定义和管理你的API。