search

swagger-api / swagger-codegen

swagger-codegen contains a template-driven engine to generate documentation, API clients and server stubs in different languages by parsing your OpenAPI / Swagger definition.
http://swagger.io
Apache License 2.0
17.03k stars 6.03k forks source link

Bad error message on accidentally nested schema. #2313

Open nicksloan opened 8 years ago

nicksloan commented 8 years ago

When I build a spec (here: https://gist.github.com/nicksloan/0ec7e74af30ac9540ccf) with a schema nested within a schema (see line #647) I am shown a less than helpful error message:

[main] WARN io.swagger.util.PropertyDeserializer - no property from null, null, {ENUM=null, TITLE=null, DESCRIPTION=Unexpected error, DEFAULT=null, PATTERN=null, DESCRIMINATOR=null, MIN_ITEMS=null, MAX_ITEMS=null, MIN_PROPERTIES=null, MAX_PROPERTIES=null, MIN_LENGTH=null, MAX_LENGTH=null, MINIMUM=null, MAXIMUM=null, EXCLUSIVE_MINIMUM=null, EXCLUSIVE_MAXIMUM=null, UNIQUE_ITEMS=null, EXAMPLE=null, TYPE=null, FORMAT=null, READ_ONLY=null, VENDOR_EXTENSIONS={}}

Using the online validator in debug mode is much more helpful in identifying the actual issue:

{"schemaValidationMessages":[{"level":"error","domain":"validation","keyword":"oneOf","message":"instance failed to match exactly one schema (matched 0 out of 2)","schema":{"loadingURI":"http://swagger.io/v2/schema.json#","pointer":"/definitions/responseValue"},"instance":{"pointer":"/paths/~1infomous-graph/get/responses/default"}}]}

The codegen version is 2.1.5 from Homebrew.

wing328 commented 8 years ago

@nicksloan agree that the error message can be more helpful.

In this case, what would you suggest to make it clearer?

Using Swagger Editor, I got Not a valid response definition

nicksloan commented 8 years ago

instance failed to match exactly one schema (matched 0 out of 2) gave me the impression that somehow there were two schemas in play, which made it obvious when I went looking. In my case, the json listed is compiled from multiple files using swagger-parser (the JavaScript one), so the nested schema properties weren't in the same file.

The big thing is that it doesn't say anything about where. Listing the path to the broken section is a huge help in tracking these things down. If nothing else is done, I think showing that would make it far more obvious. I'm not familiar with the code, but I wonder how easy it would be to add to any log entry/error/warning a path to the location in the input data structure that is currently being processed.