REST API: Import documentation descriptions from an external file

[matleppa]

Include documentation from external file

Instead of writing descriptions in same file with program code they can be written in an external file and linked into program code file.

That way the descriptions are included in generated swagger document.

[matleppa]

Comments from @brylie related to review of PR 2876.

// in catalog_api_texts.js (or some other filename)

  export catalogApiDescription = `
  Some markdown descriptive text. **APInf is so cool!**
  `

  export endpointOneDescription = `
  *Markdown* cool!
`

// in catalog_api.js

  import catalogApiDescription from './catalog_api_texts';

  {
    // catalog API swagger definition
   description: catalogApiDescription,
  }

[matleppa]

Numbers of main level (multiline) descriptions (at the moment 2017-09-18):

• 9: organizations/server/api.js
• 7: apis/server/api.js
• 8: users/collection/server/apis.js
• 1: rest_apis/server/catalog.js
• 2: rest_apis/server/management.js