2

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?

Dalton Cézane
  • 3,672
  • 2
  • 35
  • 60
  • Your definition has a mix of OpenAPI 2.0 and 3.0 syntax, hence the errors. Is it supposed to be `swagger: '2.0'` or `openapi: 3.0.0`? – Helen Oct 27 '20 at 15:23
  • Hi, @Helen . I dont know the difference between both. I have to document a code in Go. I would like to try go-swagger, but I cannot find a good tutorial. So, I am trying to see different tutorials and adapt for my code. Do you know a good reference, step by step? – Dalton Cézane Oct 27 '20 at 17:38
  • I changed some information and updated the questions as well as the output (errors). – Dalton Cézane Oct 27 '20 at 18:24

2 Answers2

0

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
Dalton Cézane
  • 3,672
  • 2
  • 35
  • 60
0

Maybe you can try to edit your swagger.yml in the online Swagger Editor.

Víctor J. Tomás
  • 1
  • 1