swagger-api / swagger-api/validator-badge

False negative if YAML has syntax error

Open
#93 0 comments 1 reaction 0 assignees View on GitHub

Nobody has claimed this yet.

Dominant language
Java
Stars
227
Forks
81
Avg merge
2h 3m
Merged PRs (30d)
1

Description

We had a developer author a relatively large swagger document that he created and exported from Swagger Editor as swagger.yaml

It would not load in swagger-ui (2.2.3) which we have deployed locally in web server

http://swagger.na.sas.com/swagger-ui/?url=http://swagger.na.sas.com/apis/swagger.bugs/validator/swagger.yaml

I got only

failed to parse JSON/YAML response

and no further indication of what was wrong. I converted the YAML to JSON and that rendered OK in the UI.

I ran it through the validator

http://swagger.na.sas.com/swagger-validator/?url=http://swagger.na.sas.com/apis/swagger.bugs/validator/swagger.yaml

and it passes, showing the badge, and in debug mode

http://swagger.na.sas.com/swagger-validator/debug?url=http://swagger.na.sas.com/apis/swagger.bugs/validator/swagger.yaml

returns

{}

I was only able to find the problem when I turned on JavaScript debugging in Chrome and set it to halt on exceptions and it flagged a YAML error related to a duplicate key in swagger-ui. I was able to find that a schema definition in the larger swagger.yaml file had two description fields. Removing the duplicate field resolved the error.

I'd like to see validator-badge detect and report on this (YAML errors); this will help identify problems. (Also having swagger-ui report the parsing problem would also help, I'll submit another report for that project)

Here is a small sample Swagger 2.0 document that is clean in the editor and validator but does not load in swagger-ui :

swagger: '2.0'
info:
  description: validator-badge does not detect yaml error that causes swagger-ui failure
  version: 1.0.0
  title: validator false negative
host: 'www.example.com'
basePath: /
paths:
  /score:
    get:
      produces:
        - application/json
      responses:
        200:
          description: A score result
          schema:
            $ref: '#/definitions/scoreResult'
definitions:
  scoreResult:
    properties:
      outputs:
        type: string
        description: the score output data
      scoreRequest:
        description: This is the description of this member.
        type: string
        description: Oops, this schema has two description members.
      version:
        type: integer
        format: int32

Contributor guide

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Research direction

Reproduce the failure with the sample Swagger 2.0 YAML and compare the validator result with the validator debug response shown in the issue. Trace how validator-badge handles YAML parsing and duplicate keys; done means the validator reports the YAML error instead of returning a successful badge or empty debug response.

Written by the indexing model from the issue text.

Assessment

Tech stack
java, yaml
Domain
api, tooling
Issue type
Bug
Difficulty
3/5
Estimated time
1-2 days
Activity status
Stale
Clarity
Mostly clear
Newbie friendliness
45/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.