Swagger / JSON — 可选字段被视为必需

Question

我在使用 Swagger 2.0 时遇到了一些困难，当字段实际上没有定义为 required 时，它们是 required。

这是我的 Swagger YML 文件的截取版本。

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'

get '/categories/awesome-cat' 的响应如下所示：

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

符合我的预期，符合我上面定义的类别。

我正在使用名为 conform_to_the_documented_model_for provided by the Apivore 项目的 swagger rspec 匹配器来验证我所有 API 端点的输出：

 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

唉，我的测试失败了。

 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'

出于某种原因，JSON 验证器不将 link 的 href 属性视为可选，也不将 children 属性的 category 作为可选。

据我了解，required 部分下未列出的属性是可选的。为什么 JSON::Validator.fully_validate 认为它们是非可选的？

Answer 1

戴夫，为了完整起见，也只是在这里回答。最新版本的 Apivore gem, 0.0.2，不再使用 JSON Validator gem json-schema 的 :strict 模式，它假设各个领域都需要。这是我在解决了围绕additionalProperties的误解后所做的最新更改。我现在认为验证器的 :strict 模式不是很有帮助。默认 JSON 模式验证是正确的，没有理由是任何 'stricter'.

确保您拥有最新版本的 Apivore gem（0.0.2 或更高版本）应该可以解决您的问题。

Swagger / JSON — 可选字段被视为必需

Swagger / JSON — Optional fields being treated as required

json

validation

rspec

swagger

apivore