Documentation & error messages: what are the allowed formats for the input API spec file?

[denis-haskin-elemental]

Describe the bug Documentation & error messages do not specify clearly whether JSON is a valid format for an input OpenAPI spec file.

To Reproduce Specify a path to a JSON file as input, e.g.

  app.use(
    OpenApiValidator.middleware({
      apiSpec: './openapi/openapi.json',
...etc...

Actual behavior Fails with this error:

openapi.validator: spec could not be read at ./openapi/openapi.json

Expected behavior The OpenAPI spec in JSON format would be read & used

Examples and context The documentation never specifies precisely whether JSON is valid input file format or not. All of the examples use a YAML filename when a file is used as input, but since JSON and YAML are often treated interchangably, it's unclear whether JSON might be valid.

Also, the could not be read message is a little vague and it would be better if it were more precise. Was the file not found? Or was it found but failed parsing? (I assume it's the latter but I'm just guessing)

[denis-haskin-elemental]

Okay, it actually turns out our problem with with the file path - so the error was really a "file not found". Would be great if the error message could be more precise.

[denis-haskin-elemental]

AND it seems like JSON is a valid file format in addition to YAML. It would be great if the documentation could be updated to reflect that.