ZMS-[9x] Automatic API generation

[NickOvt]

• ZMS-96 - Add additional data to Endpoints in the message.js file (Messages) to include them in API generation
• ZMS-97 - given an object that has key-value pairs where the value is a Joi validation object, parse that object and build a simple JS object from it with required data to generate a YAML string required for automatic API generation
• ZMS-98 - Actual API generation
  Every endpoint should be (but doesn't have to, in which case it will be ignored) converted to a new format, that will allow the given endpoint to be used for automatic API generation if the endpoint is allowed to be included in API generation,
  Data for every endpoint:

{
  path: "api route path",
  pathParams: {
    [pathParamKey]: <simple Joi object (primitive data type)>,
  },
  summary: "summary",
  description: "description",
  requestBody: {
    [requestBodyParamKey]: <Joi object>,
  },
  applicationType: "application/json or any other valid type", // if not given defaults to "application/json"
  queryParams: {
    [queryParamKey]: <simple Joi object (primitive data type)>
  },
  tags: ["Tag1"],
  response: {
    [httpStatusCode]: {
      description: "description",
      model: <Joi object>
    }
  },
  responseType: "application/json or any other valid type", // if not given defaults to "application/json"
  include: boolean // include or exclude the API Route/Endpoint from API generation. If not given then regarded as false
}

The object above ^ has to be the first parameter in the server.get, server.post, server.put, server.del function calls.

1. Define constant parts of the documentation. Such as tags, servers, info, auth, etc.
2. Go through all API Routes
3. Extract necessary data from the endpoint data, such as tags, summary, description, operationId, requestBody, parameters, responses
4. Parse all Joi objects that come along the way, if necessary parse Joi objects recursively if the object contains inner objects or it is an array or an alternatives Joi type
5. Given all data above start building the initial documentation in JS object format.
6. After the documentation initial JS object is built walk through it (if necessary recursively) to extract repeating components into separate components and replace the part with a ref to the component. (Used to comply with modern openApi documentation standards and best practices)
7. Transform JS object to YAML string with help of js-yaml package. Also as components are held in a separate JS object transform that object to YAML string as well.
8. Concatenate all YAML strings into one string
9. Write docs YAML string to a file (currently it goes to the root of the project and the file name is openapidocs.yml)

[louis-lau]

Andris is in charge of all application logic, but I though my feedback could help here 😁

Should this maybe PR be marked as draft until it's actually ready?

[NickOvt]

ZMS-96 added all POST and GET endpoints in messages.js to API generation, but as the process of adding is extremely tedious and time consuming, it is better to import existing data from the current API docs and later on just add/remove data.

[louis-lau]

For conversion from the old docs to openapi I also used an automatic process, with a lot of manual fixups afterwards :)