Search code examples
swaggerswagger-2.0go-swagger

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


I am trying to use Swagger. Below is the swagger.yml file.

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'

When I try to generate the documentation, I get the following error:

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"

What am I doing wrong?


Solution

  • To make this code pass in the Swagger validation, I had to:

    • Remove the schema in the contractId parameter (get method);
    • Remove the requestBodies definition and change the schema in the contract parameter (post method);
    • Change the type of the contractId in the Xyz definition (the uuid type is not supported by the version 2 of Swagger).

    The fixed code is below:

    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