Process whole specs for GraphQL and REST to collect per-operation data for build type changelog #30
Description
Collect operation deprecation/diff/... data from whole spec (GraphQL/REST)
Expected Result
Output (build result) does not change in scope of this story (this includes all operations data, specifications per operation and everything else)
Only implementation of how per-operations data is collected changes
- we process specification as a whole (e.g. normalize or create merged document for the specification as a whole)
- make a top-down, bottom-up specification tree traversal, aggregating all necessary data on each node
- get per-operation data from corresponding nodes and put in build result
Keep per-operation specification generation to not break existing contract, but do not use per-operation specification in any other logic in api-processor (we might get rid of it completely on subsequent stories)
api-processor from this story could be delivered as a drop-in replacement for the current one, now changes in any other component is required
Large GraphQL specifications with changelog are processed in reasonable time (minutes, not hours)
Operation Data Fields
Build type build
REST Operation
| Field | Type | Source Document Flavor | How to collect |
|---|---|---|---|
| operationId | Direct access | ||
| dataHash | Derived from data | ||
| apiType | Direct access | ||
| apiKind | Direct access | ||
| deprecated | Direct access | ||
| title | Direct access | ||
| customTags | Direct access | ||
| path | Direct access | ||
| originalPath | Direct access | ||
| method | Direct access | ||
| tags | Direct access | ||
| data | Source document with refs | Direct access | |
| searchScopes | Hierarchically | ||
| deprecatedItems | Hierarchically | ||
| models | Hierarchically | ||
| deprecatedInfo | Derived from deprecatedItems | ||
| deprecatedInPreviousVersions | Direct access in previous versions | ||
| apiAudience | Direct access |
GraphQL Operations
| Passed Value | Type | How to collect |
|---|---|---|
| operationId: "asd", | ||
| dataHash: "asdasd", | ||
| apiType: 'rest', | ||
| apiKind: API_KIND.BWC, | ||
| deprecated: false, | ||
| title: 'title', | ||
| type: 'mutation', | ||
| method: 'asd', | ||
| tags: ['mutation'], | ||
| data: { graphapi: '1.0.0' }, | ||
| deprecatedItems: [], | ||
| apiAudience: 'internal', |
Implementation Notes
One or more prototypes might be required to see how better handle specific fields
Aggregation logic most likely could be generalized- common tree traversal/cycle detection logic, customizable data retrieval/aggregation functions
Try reusing aggregated data between data nodes if it is the same to reduce memory consumption
High memory consumption is a risk especially for search scopes- appropriate data structure for aggregated search scope could be required
See if we can collect all necessary data in a single tree traversal
To get changes for the operation we need not only get aggregated changes from operation node, but also collect changes from parent nodes possibly up to the root (e.g. Path Item changes case)
Move operation between documents requires special handling when building changelog
Metadata
Metadata
Assignees
Type
Projects
Status