Workspaces

OpenAPI documents are not limited to a single file. The complete description of an API may span many physical files. The OpenAPI description itself can be spread over multiple files to either keep file sizes small, or enable the re-use of descriptions across different APIs. Other files that contain data related to the API description may be referenced via URLs in the OpenAPI descriptions. These files could contain example payloads, license documents, related documentation and other non-OAS documents.

The OpenApiWorkspace class is used to hold a collection of related documents.

The design of the API surface area for this feature is ongoing and there are a number of open questions.

• Should a workspace have a single "root" document?
• Should workspaces be created implicitly when reading a "root" document but with external reference resolution enabled?
• Should reference resolution occur when adding a document to a workspace? (I think not, because you could add references to a document after adding it to a workspace)
• If you load a second OpenApiWorkspace, can it be loaded into the same workspace?

Requirements

• Enable loading an OpenAPI Description and all of its dependent documents. As a developer may not know in advance if there are external references, they should not be required to use a different code path to load connected document. This leads down the path of creating workspaces implicitly.
• A developer should be able to construct an OpenApiWorkspace with multiple related files
• We should be able to persist the OpenApiWorkspace to a set of files
• We should be able to inline the external references to OAS descriptions into a single file.
• We should be able to package all the OpenApiWorkspace into a single combined package (e.g. a zip file, or a multipart document)