fixes for multiple documents

karenetheridge / OpenAPI-Modern

Validate HTTP requests and responses against an OpenAPI v3.1 document

https://metacpan.org/release/OpenAPI-Modern/

Other

3 stars 3 forks source link

fixes for multiple documents #73

Open karenetheridge opened 5 months ago

karenetheridge commented 5 months ago

A few places make assumptions that we are only ever working with one document. But actually a $ref can point to an entity in another document entirely.

Most ref resolutions work properly, updating $state with the proper base uri, as we use JSON Schema semantics and its helper subs to work with references. However some issues remain:

operationId and operationId_path is on the document, not the openapi object
- operation ids could conceivably be duplicated across multiple documents when loaded, and this should result in an error when the second document is loaded;
- when working with a user-provided operationId, we should check the indexes of all loaded documents for this operationId, not just our own (this will require a new helper method)
- operationId_path is used verbatim in 'schema_path', which is supposed to contain a chain of $refs if references were followed to reach the path-item - so this will break even with a single document if the path to the path-item contains a $ref.

karenetheridge commented 5 months ago

We're not testing multiple documents, so how this is to be handled might need to be changed in the interfaces.

Since we call add_schema on the JSM object to add documents, we can't do any checking at add-document time to look for duplicate operation ids etc. we'll have to do the dupe check at runtime -- but that's ok, we can just iterate over all the known documents and query each one for the operation id (and we can't cache anything bcause a new document might be added at any time).

karenetheridge commented 5 months ago

This should be a public method, so that the user can always find the operation, given either the operationId or the http request method and the path_item_uri (these might not be available if only validating a response without an associated request).

karenetheridge commented 4 months ago

see also https://learn.openapis.org/specification/servers.html: "Be aware that if your OAD is split across multiple documents, each endpoint id assumed to be relative to the document in which it is described." -- this might change for v3.2, but in the meantime we need to be aware of the root URL of the document containing the path-item we are operating on.

karenetheridge commented 3 months ago

We also need to account for the possibility of having more than one "complete" openapi document. This has implications for searching /paths/* when validating requests and responses, and handling collisions/conflicts between these documents.

karenetheridge commented 1 month ago