无效的 Swagger 规范:"swagger.yml" 处的 swagger 规范对 swagger 规范 2.0 无效

Invalid Swagger spec: swagger spec at "swagger.yml" is invalid against swagger specification 2.0

我正在尝试使用 Swagger。下面是 swagger.yml 文件。

swagger: "2.0"
basePath: /myapp/api
info:
  description: My description
  title: My title
  version: 0.1.0
produces:
  - application/json
consumes:
  - application/json
schemes:
  - http
paths:
  /contract:
    get:
      operationId: "Get contract"
      description: Get information
      parameters:
        - in: path
          name: contractId
            description: ID
          required: true
          schema:
            type: integer
      responses:
        200:
          description: Information...
          schema:
            $ref: "#/definitions/contract"
        404:
          description: "Not found."
    post:
      operationId: "Create"
      parameters:
        - in: body
          name: contractId
          schema:
            $ref: '#/definitions/requestBodies/contract'
      responses:
        200:
          description: Success...
        400:
          description: Problem...
definitions:
  contract:
    title: Contract
    type: object
    properties:
      name:
        title: Name
        type: string
      services:
        title: Services
        type: array
        items:
          title: Service
          $ref: '#/definitions/service'
      xyz:
        title: Xyz
        $ref: '#/definitions/virtualMachine'
  service:
    title: Service
    type: object
    properties:
      containerName:
        title: ContainerName    
        type: string
      ...
      contracts:
        title: Contracts
        type: array
        items:
          title: Contract
          $ref: '#/definitions/contract'    
  xyz:
    title: Xyz 
    type: object
    properties:
      serverId:
        title: ServerID
        type: string
      contractId:
        title: ContractID
        type: uuid  
      ...  
  requestBodies:
    contract:
      content:
        application/json:
          schema:
            $ref: '#/definitions/contract'

当我尝试生成文档时,出现以下错误:

swagger generate server -f swagger.yml 
2020/10/26 15:43:31 validating spec /home/dalton/workspace/.../.../swagger.yml
The swagger spec at "/home/dalton/workspace/.../.../swagger.yml" is invalid against swagger specification 2.0. see errors :
- definitions.requestBodies.contract in body is a forbidden property
- "definitions.xyz.properties.contractId.type" must validate at least one schema (anyOf)
- definitions.xyz.properties.contractId.type in body must be of type array: "string"

我做错了什么?

为了让这段代码通过 Swagger 验证,我必须:

  • 去掉contractId参数中的schema(get方法);
  • 删除requestBodies定义并更改contract参数中的schema(post方法);
  • 更改Xyz定义中contractId的类型(Swagger version 2不支持uuid类型)

固定代码如下:

swagger: "2.0"
basePath: /myapp/api
info:
  description: My description
  title: My title
  version: 0.1.0
produces:
  - application/json
consumes:
  - application/json
schemes:
  - http
paths:
  /contract:
    get:
      operationId: "Get contract"
      description: Get information
      parameters:
        - in: path
          name: contractId
          description: ID
          required: true
          type: integer
      responses:
        200:
          description: Information...
          schema:
            $ref: "#/definitions/contract"
        404:
          description: "Not found."
    post:
      operationId: "Create"
      parameters:
        - in: body
          name: contractId
          schema:
            $ref: '#/definitions/contract'
      responses:
        200:
          description: Success...
        400:
          description: Problem...
definitions:
  contract:
    title: Contract
    type: object
    properties:
      name:
        title: Name
        type: string
      services:
        title: Services
        type: array
        items:
          title: Service
          $ref: '#/definitions/service'
      xyz:
        title: Xyz
        $ref: '#/definitions/virtualMachine'
  service:
    title: Service
    type: object
    properties:
      containerName:
        title: ContainerName    
        type: string
      ...
      contracts:
        title: Contracts
        type: array
        items:
          title: Contract
          $ref: '#/definitions/contract'    
  xyz:
    title: Xyz 
    type: object
    properties:
      serverId:
        title: ServerID
        type: string
      contractId:
        title: ContractID
        type: string
        format: uuid  

也许您可以尝试在在线 Swagger Editor 中编辑您的 swagger.yml。