Spike: Investigate how schema documentation can be automated

[iapaddler]

Identify options for automating the documentation of schema.

[michalbiesek]

My potential expectation about the solution would be:

• easy to maintain
• provide a validation for it, e.g. in a situation that we change some behavior in the code logic and documentation generation schema is not aware of it
• different output formats? html/pdf

Idea 1

• Automation based on code comments and tools which was designed for C and/or JSON (Doxygen/clang-doc)

• Advantage: we will not have yet another file to maintain separately

• Advantage: we can use this additionally to generate dev-documentation

• Disadvantage: I think in our codebase should be some code adjustment regarding how the events/metrics are generated

Idea 2

• Use the code logic for generating events/metrics. We can similar approach like was used in the unit tests.

• Advantage: we will use the same code logic as in the AppScope logic

• Disadvantage: need to check if we can actually handle all the logic with expected output with minimal effort in changes

Idea 3

• Use an external tool and store the configuration of schema in a separate file - json-schema.

• Advantage: feasible approach - the dedicated configuration file can be customized to place in output different fields, like e.g. information about changes between the version of the Appscope, the tool will be just responsible for generating the proper output

• Disadvantage: yet another file to maintain

[michalbiesek]

After discussion, a valid approach can be based on all of the three solutions mentioned above:

The diagram below is a simplification of my thoughts:

1.

Store the Appscope Logic - the structure of events/messages in JSON Scheme file(s)
We can use the Unit Test model by creating a Message generator a separate test binary - to extract functions like e.g. doFsMetric functions to generate exact messages which are generated on the AppScope side. Generated messages can be used to simplify the creation/maintain the JSON Scheme file.

2.

The document generation is based on JSON Scheme file. In JSON Scheme file besides storing the logic of events/metrics we can extend the description with information on what controls the event how to enable/disable it, what controls the aggregation, and dimensions. Therefore JSON Schema file can be used to generate proper documentation in different variants like markdown, pdf, html.

3.

The same JSON Scheme file can be used for validation. In long term solution, we can use it in our validation process by checking if messages generated by the Appscope are inline with schema e.g. that we will not add some field to an event without adding it to documentation.
Therefore we will ensure that generated documentation is inline with AppScope Logic.

[michalbiesek]

Current state:

• after discussion, we decide to go with a solution to use one JSON schema file for each event source - not one JSON schema file for all events.
• The JSON schema file will be stored under docs/schemas
• The tools that can be used for doc generation; https://json-schema.org/implementations.html#documentation-generators
• Initial implementation will be done manually while working on Create JSON Schema for events and metrics #725