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? I believe the answer is no. A workspace should be able to hold API descriptions for multiple APIs that share common components.
• Should workspaces be created implicitly when reading a "root" document but with external reference resolution enabled? (This is how it is now implemented)
• 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 read a second OpenApiDocument, can it be loaded into the same workspace? I think this would be a multi step process. Use a reader to load a document without resolving external references, then add it to the workspace.
• What happens to a document that is associated to a workspace when someone tries to add it to another 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)
• Loading of streams should be limited to the OpenApi.Reader project. The OpenApiWorkspace class should do zero IO.