Automate APInf platform APIs swagger creation

[kyyberi]

APInf Platform has currently one big API for dealing with users, APIs, organisations etc. A single Swagger file will be pulled from code comments automatically (see #2638). Aim is not to show one huge API in APInf catalog, but atm 2 APIs: APInf Catalog API and APInf Management API.

Thus we need to create script which will devide the big Swagger file into two separate Swagger files. Pulling methods from code to Swagger file does not provide good enough developer experience. Thus we need to inject more decriptive description in the beginning of both Swagger files. The descriptions are maintained in Github (specific folder and file names needs to defined).

Process roughly for APInf Catalog API:

• Read big Swagger file in
• Select approriate parts (methods, data model descriptions needed, host information, contact information, security descriptions needed) from file.
• Replace "description:" content with file content taken from Github (catalog-description.md?)
• validate result
• Save file as apinf-catalog-rest-api.yml

Same process with APInf Management API.

[matleppa]

A part of these requirements are resolved in PR #2754 .

• There are generated two separate swagger files: one for APInf Catalog API (catalog.json) and another for APInf Management API (management.json).
• Using backtick as a separator (examined in issue #2755 ) it is possible to include long and detailed descriptions in files generating swagger documents

With this solution the changes needed in description texts need to be handled as issues. The optimal solution would be possibility to link e,g, *.md text files to files generating swagger documents, however it needs to be examined, if it is possible.

[bajiat]

Closing as resolved.