0

I'm having some difficulty with Swagger 2.0 insiting that fields are required when they are not in fact defined to be required.

Here's a snipped version of my Swagger YML file.

definitions:
  category:
    type: object
    required:
      - name
      - code
    properties:
      name:
        type: string
        description: Category name
      code:
        type: string
        description: Category code
      _links:
        $ref: '#/definitions/categoryLinks'
      children:
        type: array
        items:
          $ref: '#/definitions/category'

  categoryLinks:
    required:
      - self
      - parent
      - children
    properties:
      self:
        description: Canonical link to this category
        $ref: '#/definitions/genericLink'
      parent:
        description: Link to the parent category
        $ref: '#/definitions/genericLink'
      children:
        description: Link to the child categories
        $ref: '#/definitions/genericLink'

  genericLink:
    properties:
      href:
        type: string
        description: The absolute URL being linked to.

paths:
  '/categories/{category_code}':
    get:
      summary: Get a specific category
      description: Returns information about a specific category.
      parameters:
        - name: category_code
          description: Code of category to get
          type: string
          in: path
          required: true
      responses:
        200:
          description: Information about requested category.
          schema:
            $ref: '#/definitions/category'

The response from get '/categories/awesome-cat' looks like:

{
    "name" => "My awesome Category",
    "code" => "awesome-cat",
    "_links" => {
        "self" => {
            "href" => "https://api.test.testing/categories/awesome-cat.json"
        },
        "parent"=> {},
        "children" => {}
    }
}

Which is as expected, and which conforms to my definiton of a category above.

I'm using the swagger rspec matcher called conform_to_the_documented_model_for provided by the Apivore project to validate the output from all my API endpoints:

 matcher :conform_to_the_documented_model_for do |swagger, fragment|
   match do |body|
     body = JSON.parse(body)
     @errors = JSON::Validator.fully_validate(swagger, body, fragment: fragment)
     @errors.empty?
   end

   failure_message do |body|
     @errors.map { |e| e.sub("'#", "'#{path}#").gsub(/^The property|in schema.*$/,'') }.join("\n")
   end
 end

Alas my test is failing.

 3) the V1 API path /categories/{category_code} method get response 200 responds with the specified models
    Failure/Error: expect(response.body).to conform_to_the_documented_model_for(swagger, fragment)
       '#/_links/parent' did not contain a required property of 'href' 
       '#/_links/children' did not contain a required property of 'href' 
       '#' did not contain a required property of 'children'

For some reason the JSON validator is not regarding the href property of the link as optional, nor is it regarding rhe children property of category as optional.

It was my understanding that properties not listed under the required section are optional. Why is the JSON::Validator.fully_validate regarding them as non-optional?

Dave Sag
  • 13,266
  • 14
  • 86
  • 134
  • Two things - a. It sounds like a bug with Apivore and you probably want to open a bug on it rather than ask here. b. I really hope the snippet above is *not* the actual response from your API as that is not JSON and cannot be described with Swagger. – Ron Apr 19 '15 at 13:35
  • Sure there is a bunch of wrapper around the actual response but the snippet above is the core of the returned category. WRT bug in Apivore, yes - that's my gut feeling but since the Apivore matcher is ultimately just using `JSON::Validator.fully_validate` it seems that the 'error' is in that. Which is a worry. – Dave Sag Apr 19 '15 at 22:48

1 Answers1

2

Dave, just answering here too for completeness. The latest version of the Apivore gem, 0.0.2, no longer uses the :strict mode of the JSON Validator gem json-schema, which makes the assumption that all fields are required. This is a recent change I made after we sorted out the misunderstandings around additionalProperties. I am now of the opinion that the :strict mode of the validator isn't very helpful. The default JSON schema validation is correct, there is no reason to be any 'stricter'.

Making sure you have the latest version of the Apivore gem (0.0.2, or greater) should solve your problem.

Charles
  • 36
  • 4