Normalizing/building merged document for large REST/GraphQL specifications could take dozens of seconds. This is too much for on-the-fly processing. We want to be able to cache processing results to the BE and get this processed specs when we want to present them in UI.
This story is for the implementation on backend of corresponding functionality.
High-level we want to be able to

• store normalized (pre-processed) documents for version
• store merged (pre-processed) documents for version comparison
• associate operations with these documents
• be able to get pre-processed document for version/version comparison

Proposed design and API:

Proposed API is in this PR: Netcracker/qubership-apihub-backend#227

Version internal documents

version-internal-documents folder

Build results of type build and changelog could contain version-internal-documents folder in which zero or more documents could be present. Note: version internal documents folder could be absent if the version(s) does not contain actual API of supported type (e.g. only md or pdf files). It is expected that the documents from the version-internal-documents folder will be persisted by backend for the package version and could be later retrieved using corresponding API.

version-internal-documents.json

Build results of type build and changelog could contain version-internal-documents.json file, which provides metadata for files in version-internal-documents folder. If there are files in version-internal-documents folder, version-internal-documents.json shall be present. If there's no version-internal-documents folder, the version-internal-documents.json will be also not provided in build results.

Internal document for an operation

Operation in operations.json file will have mandatory versionInternalDocumentId property, value shall correspond to one of the internal documents described in version-internal-documents.json file. It should be stored for the operation and returned in corresponding end-points that return operations, e.g. Get list of operations.

API to get internal documents for the package version

/api/v1/packages/{packageId}/versions/{version}/version-internal-documents

API to get content of version internal document

/api/v1/version-internal-documents/{hash}

Comparison internal documents

comparison-internal-documents folder

Build results of type changelog could contain comparison-internal-documents folder in which zero or more documents could be present. Note: comparison internal documents folder could be absent if the version(s) does not contain actual API of supported type (e.g. only md or pdf files). It is expected that the documents from the comparison-internal-documents folder will be persisted by backend for the comparison and could be later retrieved using corresponding API.

comparison-internal-documents.json

Build results of type changelog could contain comparison-internal-documents.json file, which provides metadata for files in comparison-internal-documents folder. If there are files in comparison-internal-documents folder, comparison-internal-documents.json shall be present. If there's no comparison-internal-documents folder, the comparison-internal-documents.json will be also not provided in build results.

Internal document for an operation comparison

Comparisons data in comparisons/{comparisonFileId} will have a mandatory comparisonInternalDocumentId property, value shall correspond to one of the internal documents described in comparison-internal-documents.json file. It should be stored for the operations comparison and returned in corresponding end-points that return them, e.g. Get list of changed operations.

API to get internal documents for the package version comparison

/api/v1/packages/{packageId}/versions/{version}/comparison-internal-documents

API to get content of comparison internal document

/api/v1/comparison-internal-documents/{hash}