SwaggerHub编辑器3项Schema错误排查求助（附YAML代码）

Hey there! Let's work through these Swagger schema errors step by step—they're all related to how you've structured your 7th parameter (index 6) in the /addWish.php POST endpoint. Here's what's going wrong and how to fix each issue:

1. Why you're seeing "不应包含额外属性（type、items、name、in、description、required）" #

In Swagger, parameter objects follow a strict structure: properties like name, in, description, and required belong at the top level, but type, items, and schema references must live inside a schema sub-object. You’ve likely placed those schema-related properties directly on the parameter itself, which violates the Swagger spec.

2. Why "in的值不在允许值列表（header、formData、query、path）内" #

The in field defines where the parameter is passed, and only those four values are valid. If you tried using body here:

• For Swagger 2.0: You can have one body parameter, but it still needs to follow the correct structure (with a schema sub-object).
• For Swagger 3.0 (OpenAPI 3.x): body parameters are replaced entirely by requestBody—you shouldn’t include them in the parameters array at all.

3. Why "items不应包含额外属性$ref" #

This ties back to the first issue: your items property is on the parameter object instead of being nested under schema.items. When items is in the correct place, using $ref to reference a schema is totally allowed.

Fix Example (Swagger 2.0) #

Let’s assume your problematic parameter is an array of wish items passed in the request body. Here’s the corrected structure:

swagger: '2.0'
info:
  title: Wish API
  version: 1.0.0
paths:
  /addWish.php:
    post:
      summary: Add a new wish
      parameters:
        # ... Your first 6 parameters go here ...
        - name: wishItems
          in: body  # Valid for Swagger 2.0 (only one body parameter allowed)
          required: true
          description: List of items to add to the wish
          schema:  # Schema-related properties live here
            type: array
            items:
              $ref: '#/definitions/WishItem'
      responses:
        200:
          description: Wish added successfully
definitions:
  WishItem:
    type: object
    properties:
      id:
        type: integer
      name:
        type: string

If you're using OpenAPI 3.x (Swagger 3.0) #

Replace the body parameter with a requestBody block instead:

openapi: 3.0.0
info:
  title: Wish API
  version: 1.0.0
paths:
  /addWish.php:
    post:
      summary: Add a new wish
      parameters:
        # ... Your first 6 parameters go here (no body parameter!) ...
      requestBody:
        required: true
        description: List of items to add to the wish
        content:
          application/json:
            schema:
              type: array
              items:
                $ref: '#/components/schemas/WishItem'
      responses:
        '200':
          description: Wish added successfully
components:
  schemas:
    WishItem:
      type: object
      properties:
        id:
          type: integer
        name:
          type: string

Double-check that all your parameters follow this pattern: top-level properties for parameter metadata, and a schema (or content for OpenAPI 3.x) block for data type details. That should resolve all three errors!

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