openapi-model - roadmap to v1.0

[mykulyak]

Overview

Let's discuss what is left to implement and improve in the @fresha/openapi-model package, before showing it to general audience.

The @fresha/openapi-model is the single most important package in this project, serving as a foundation for tools directly used by developers.

OpenAPI 3.0

1. Make the programmatic API conform to coding guidelines

As of today, this includes:

• replacing raw attributes with getters and setters (✅)
• replacing collection attributes with member functions (✅)
• use consistent naming (✅)
  • deduplicate interfaces (here I mean e.g. CallbackModelMap representing sets of methods operating on collection of models of the same type)
  • replace type aliases with interfaces (they are better for performance and readability) (✅ for models)

2. Introduce Reference models

Currently, a schema node has the parent property which references a node that owns the current node. However, a node may also be referenced from other nodes which do not own it. In this case, the node of interest does not know anything about nodes referring to it. This should be fixed by introducing a Reference-like nodes. Whenever a node is referenced but not owned by another node, there should be a reference node inbetween.

Example (current state):

OpenAPI:
  Components:
    SomeSchema // this node is owned by the components model
  Paths:
    PathItem:
      Operation:
        RequestBody:
          // currently, this property points to SomeSchema, but SomeSchema does not know anything about it. 
          // This complicates mutations (there should be a map of references node somewhere), tree walking 
          // (it is not possible to go upwards the tree), as well as deserialising OpenAPI schemas. It also makes it
          // very difficult to implement JSON pointers in schema nodes.
          schema: SomeSchema 

Example (target state):

OpenAPI:
  Components:
    // this node is owned by the components
    SomeSchema 
  Paths:
    PathItem:
      Operation:
        RequestBody:
          // Now this is a separate node, referring to SomeSchema. 
          // Its sole parent (and owner) is the RequestBody,
          // whereas the SomeSchema's parent is Components
          schema: Reference<Schema>

This approach will ensure that each node will have a single parent (which will also be an owner of that node).

3. Extend programmatic API

There is a need for easy walking the tree nodes.

As of today, this included extending the TreeNode and TreeRoot interface to the following shape:

interface TreeRoot {
  childen<T>(): IterableIterator<TreeNode<T>>;

  findNode(jsonPointer: JSONPointer): TreeNode<T>;
}

interface TreeNode<TParent> {
  readonly root: TreeRoot;
  readonly parent: TParent; //
  readonly kind: TreeNodeKind; // enumeration of possible node types
  children(): IterableIterator<Node>;

  readonly jsonPointer: JSONPointer;
}

4. Improve reading / writing code for OpenAPI 3.0

Currently information about e.g. attribute order in the original YAML file is lost after deserialisation. This results in e.g. openapi-lint producing much more changes than necessary, because it requires everything to be sorted.

Also, the code of OpenAPIReader and OpeAPIWriter is cluttered. Partly it is because of inconsistent interface of model classes themselves, but not only. Both classes also lack tests.

5. make models for OpenAPI 3.0 support mutations

By this I mean that adding e.g. a setting ID of some operation should validate its value, and prevent appearing duplicate IDs.

Also, there must be a way to listen for mutation events from the schema itself, which will be useful inside the Designer app.

6. unify programmatic APIs of models for OpenAPI 3.0 and OpenAPI 3.1