为什么我的 swagger-server 会产生错误？

Question

从 Swagger Editor 上的“Generate Server”启动 nodejs-server 中的 index.js 时，我收到了有关 swagger yaml 的以下错误。

    #/paths/~1botManagement~1deleteScenario~1/delete/parameters/2: Not a valid parameter definition
    #/paths/~1botManagement~1deleteScenario~1/delete/parameters/2: Not a valid parameter definition
      #: Missing required property: schema
      #: Missing required property: type
    #/paths/~1botManagement~1deleteScenario~1/delete/parameters/2: Missing required property: $ref
  #/paths/~1botManagement~1deleteScenario~1/delete/parameters/1: Not a valid parameter definition
    #/paths/~1botManagement~1deleteScenario~1/delete/parameters/1: Not a valid parameter definition
      #: Missing required property: schema
      #: Missing required property: type
    #/paths/~1botManagement~1deleteScenario~1/delete/parameters/1: Missing required property: $ref
  #/paths/~1botManagement~1deleteScenario~1/delete/parameters/0: Not a valid parameter definition
    #/paths/~1botManagement~1deleteScenario~1/delete/parameters/0: Not a valid parameter definition
      #: Missing required property: schema
      #: Missing required property: type
    #/paths/~1botManagement~1deleteScenario~1/delete/parameters/0: Missing required property: $ref
  #/paths/~1botManagement~1stopScenario~1/post/parameters/2: Not a valid parameter definition
    #/paths/~1botManagement~1stopScenario~1/post/parameters/2: Not a valid parameter definition
      #: Missing required property: schema
      #: Missing required property: type
    #/paths/~1botManagement~1stopScenario~1/post/parameters/2: Missing required property: $ref
  #/paths/~1botManagement~1stopScenario~1/post/parameters/1: Not a valid parameter definition
    #/paths/~1botManagement~1stopScenario~1/post/parameters/1: Not a valid parameter definition
      #: Missing required property: schema
      #: Missing required property: type
    #/paths/~1botManagement~1stopScenario~1/post/parameters/1: Missing required property: $ref
  #/paths/~1botManagement~1stopScenario~1/post/parameters/0: Not a valid parameter definition
    #/paths/~1botManagement~1stopScenario~1/post/parameters/0: Not a valid parameter definition
      #: Missing required property: schema
      #: Missing required property: type
    #/paths/~1botManagement~1stopScenario~1/post/parameters/0: Missing required property: $ref
  #/paths/~1botManagement~1restartScenario~1/post/parameters/2: Not a valid parameter definition
    #/paths/~1botManagement~1restartScenario~1/post/parameters/2: Not a valid parameter definition
      #: Missing required property: schema
      #: Missing required property: type
    #/paths/~1botManagement~1restartScenario~1/post/parameters/2: Missing required property: $ref
  #/paths/~1botManagement~1restartScenario~1/post/parameters/1: Not a valid parameter definition
    #/paths/~1botManagement~1restartScenario~1/post/parameters/1: Not a valid parameter definition
      #: Missing required property: schema
      #: Missing required property: type
    #/paths/~1botManagement~1restartScenario~1/post/parameters/1: Missing required property: $ref
  #/paths/~1botManagement~1restartScenario~1/post/parameters/0: Not a valid parameter definition
    #/paths/~1botManagement~1restartScenario~1/post/parameters/0: Not a valid parameter definition
      #: Missing required property: schema
      #: Missing required property: type
    #/paths/~1botManagement~1restartScenario~1/post/parameters/0: Missing required property: $ref
  #/paths/~1botManagement~1startScenario~1/post/parameters/2: Not a valid parameter definition
    #/paths/~1botManagement~1startScenario~1/post/parameters/2: Not a valid parameter definition
      #: Missing required property: schema
      #: Missing required property: type
    #/paths/~1botManagement~1startScenario~1/post/parameters/2: Missing required property: $ref
  #/paths/~1botManagement~1startScenario~1/post/parameters/1: Not a valid parameter definition
    #/paths/~1botManagement~1startScenario~1/post/parameters/1: Not a valid parameter definition
      #: Missing required property: schema
      #: Missing required property: type
    #/paths/~1botManagement~1startScenario~1/post/parameters/1: Missing required property: $ref
  #/paths/~1botManagement~1startScenario~1/post/parameters/0: Not a valid parameter definition
    #/paths/~1botManagement~1startScenario~1/post/parameters/0: Not a valid parameter definition
      #: Missing required property: schema
      #: Missing required property: type
    #/paths/~1botManagement~1startScenario~1/post/parameters/0: Missing required property: $ref

yaml 文件在下面。

swagger: "2.0"
info:
  description: I wrote something but can't describe it.
  version: 1
  title: I wrote something but can't describe it.
  termOfService: I wrote something but can't describe it.
  contact:
    email: xxxx@xxxx
  license:
    name: Apache 2.0
    url: http://www.apache.org/licenses/LICENSE-2.0.html
host: xxxx.xxxx.xxxx.xxxx
basePath: /v1
tags:
  - name: I wrote something but can't describe it.
schemes:
  - https
paths:
  /XXXXXXXXXX:
    get:
      summary: I wrote something but can't describe it.
      description: I wrote something but can't describe it.
      responses:
        200:
          description: Successful response
          schema:
            type: object
            properties:
              pid:
                type: integer
                format: int64
                example: 0
              name:
                type: string
                example: sample
              pm2_env:
                type: object
                example: {username:sample, windowsHide:true...}
              pm_id:
                type: integer
                format: int64
                example: 0
              monit:
                type: object
                example: {memory:0, cpu:0}
        404:
          description: API not found
        500:
          description: Internal server error

  /xxxxx/xxxxx:
    post:
      summary: I wrote something but can't describe it.
      description: I wrote something but can't describe it.
      parameters:
        - name: xxxxx
          in: formData
          description: I wrote something but can't describe it.
          required: true
          type: string
        - name: xxxxx
          in: formData
          description: I wrote something but can't describe it.
          required: false
          type: string
        - name: xxxxx
          in: formData
          description: I wrote something but can't describe it.
          required: false
          type: string
      responses:
        200:
          description: Successful response
          schema:
            type: object
            properties:
              scenario:
                type: string
                example: sample.js
              status:
                type: string
                example: I wrote something but can't describe it.
        400:
          description: I wrote something but can't describe it.
        404:
          description: "API not found"
        500:
          description: "Internal server error"

  /xxxxx/xxxxx/:
    post:
      summary: I wrote something but can't describe it.
      description:
          I wrote something but can't describe it.
      parameters:
        - name: xxxxx
          in: formData
          description: I wrote something but can't describe it.
          required: true
          type: string
        - name: xxxxx
          in: formData
          description: I wrote something but can't describe it.
          required: false
          type: string
        - name: xxxxx
          in: formData
          description: I wrote something but can't describe it.
          required: false
          type: string
      responses:
        200:
          description: Successful response
          schema:
            type: object
            properties:
              scenario:
                type: string
                example: sample.js
              status:
                type: string
                example: I wrote something but can't describe it.
        400:
          description: Bad request
        404:
          description: API not found
        500:
          description: Internal server error

  /xxxxx/xxxxx/:
    post:
      summary: I wrote something but can't describe it.
      description:
          I wrote something but can't describe it.
      parameters:
        - name: xxxxx
          in: formData
          description: I wrote something but can't describe it.
          required: true
          type: string
        - name: xxxxx
          in: formData
          description: I wrote something but can't describe it.
          required: false
          type: string
        - name: xxxxx
          in: formData
          description: I wrote something but can't describe it.
          required: false
          type: string
      responses:
        200:
          description: Successful response
          schema:
            type: object
            properties:
              scenario:
                type: string
                example: sample.js
              status:
                type: string
                example: I wrote something but can't describe it.
        400:
          description: Bad request
        404:
          description: API not found
        500:
          description: Internal server error

  /xxxxx/xxxxx/:
    delete:
      summary: I wrote something but can't describe it.
      description:
          I wrote something but can't describe it.
      parameters:
        - name: xxxxx
          in: formData
          description: I wrote something but can't describe it.
          required: true
          type: string
        - name: xxxxx
          in: formData
          description: I wrote something but can't describe it.
          required: false
          type: string
        - name: xxxxx
          in: formData
          description: I wrote something but can't describe it.
          required: false
          type: string
      responses:
        200:
          description: Successful response
          schema:
            type: object
            properties:
              scenario:
                type: string
                example: sample.js
              status:
                type: string
                example: I wrote something but can't describe it.
        400:
          description: Bad request
        404:
          description: API not found
        500:
          description: Internal server error

它看起来缺少“$ref”的属性。 我知道这个属性是用来做什么的。但我不需要对其他文档的任何参考。 在这种情况下，我该如何解决这个问题？

Answer 1

您的定义有语法错误。

1) version 需要一个字符串值，所以它应该是version: '1'，而不是version: 1。不带引号的1 被解析为数字。

2) example: {username:sample, windowsHide:true...} 不是有效的 YAML，应该是

example:
  username: sample
  windowsHide: true

或使用 JSON 语法：

example: {"username": "sample", "windowsHide": true}

其他内联对象示例也是如此。

3) 使用in: formData 参数的操作应在consumes 关键字中指定application/x-www-form-urlencoded 或multipart/form-data：

consumes:
  - application/x-www-form-urlencoded

如果没有看到您的实际定义，很难说还有什么问题。您可以将 YAML 粘贴到 https://editor.swagger.io 以检查语法错误，或者如果您的定义有公共 URL，请使用在线验证器

http://online.swagger.io/validator/debug?url=YOUR_URL