fixes for multiple documents

[karenetheridge]

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]

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]

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]

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]

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]

See also

• Proposal: Bundled streams w/ self-identification OAI/OpenAPI-Specification#3875

[karenetheridge]

When fixing the operation fetcher, see also https://metacpan.org/release/GETTY/Langertha-0.004/source/lib/Langertha/Role/OpenAPI.pm#L54-76

[karenetheridge]

We should provide some additional helper methods to make it easier to work with multiple documents:

• like "get operation by id", also provide a getter for the list of all operationIds
• also "get * by name" and "get all * names" for webhooks, and all the entities under /components/*. NOTE: This implies that these things need to be globally unique (like operationId): does the specification actually include this restriction? If not, what do we do when there is a collision? Are global getter methods useless in that case, and the user should simply do $document->get('/components/callbacks/foo') etc?

[karenetheridge]

IF we are supporting multiple documents being collected together to create an OpenAPI description:

• the OM object also needs to keep a list of documents; we can't just use the JSM object for this (other documents that aren't openapi documents will be held there)
• we need an add_document interface in OpenAPI::Modern (that calls add_schema/add_document in JSM if not already added)
• if the "entry" document is significant, we need a boolean attribute to indicate this
• we currently check that $refs go to the right entity, but we need to also check that they go to a valid openapi document object (or if it's a schema it can go to a base class document object too).

IF we are supporting only a single "entry" document, then:

• the existing openapi_document attribute is fine, as this holds the entry document
• add_document is not needed on the OpenAPI::Modern object
• add_schema on the JSM object is sufficient for making OM documents available for referencing
• we will not consider paths, operationIds etc in other documents.

see https://handrews.github.io/renderings/oas/deploy/oas/v3.1.1.html#resolving-implicit-connections

[karenetheridge]

• until we resolve this in the spec, can support multiple modes:

  • top level things (paths, tags...) are used from all docs collectively (taken in the order that the documents were added, if relevant e.g. for linear searching/matching)
  • top level things are only taken from the entry document

• need to check for collisions across docs for operationId always

• need to check for collisions across docs for top level things (tags, security schemes...) iff we allow these to come from all documents, not just the entry doc.