search

microsoft / OpenAPI.NET

The OpenAPI.NET SDK contains a useful object model for OpenAPI documents in .NET along with common serializers to extract raw OpenAPI JSON and YAML documents from the model.
MIT License
1.41k stars 232 forks source link

How should I decide which diagnostics are mission-critical? #372

Open selman92 opened 5 years ago

selman92 commented 5 years ago

While parsing a swagger document sometimes there are errors in diagnostics but the Paths still contain the API operations, and I can parse the document even though there were some warnings/errors.

Now my question is, how can I decide what error is mission-critical? meaning that it indicates the file is INVALID, and should NOT be parsed? It would be nice if there were some kind of severity flag in the diagnostics.Errors.

Note: By "parsing" I mean parsing the requests/operations. I don't need the response objects etc.

darrelmiller commented 5 years ago

The general approach we have taken is that we generate errors when we find documents that don't comply with the specification. We do our best to parse whatever we are given. We try not force our opinions on whether you are prepared to accept a document that violates the specification.

You can change the default set of validation rules that we run if you don't want to be notified of certain types of errors. However, ideally you shouldn't see any errors. Can you give us some examples of the types of errors that you are seeing?

selman92 commented 5 years ago

I get errors about response object not containing a definition etc. In my use case, I don't need the response object at all. Only thing I need is the operations/paths. So I can ignore those errors but there is no type or severity information in the errors. I will look into the validation rules if it works for my case.

PerthCharern commented 5 years ago

We don't add severity level to the existing rules because these errors are all spec-violating. In principle, our library should not enforce any standards beyond what the spec requires, so we should not have more than one level of errors - everything is either spec-compliant or spec-violating, but nothing "in between" or "beyond".

That said, this doesn't mean that you can't generate a spec-violating document. In fact, that's why we still allow the reader to generate a document that's not spec-compliant, and do the validation separately. As @darrelmiller suggested, if you have a use case that is a bit more lax and doesn't require some of these rules, you can build your own rule sets by adding some of the rules that we created that you care about and possibly writing more rules on your own.

Regarding the specific rule about "response object not containing a definition", did you mean a "description"? If that's the case, then that rule is already enforcing the spec correctly. If not, let me know and I can investigate further. I am trying to figure out if there are any rules in our code that are not correct.