Merge pull request #5 in ~VLE2FE/dfop-api from oas_x-doc to develop

* commit '57152c1ab2c5c5604f8472af1d19a38dc7c36aaf':
  implemented feature

api/measurement.yaml

@@ -76,6 +76,7 @@
   post:
     summary: TODO add measurement
     description: 'Auth: basic, levels: write, maintain, dev, admin'
+    x-doc: 'Adds status: 0 automatically'
     tags:
       - /measurement
     security:

src/api.ts

@@ -0,0 +1,42 @@
+import swagger from 'swagger-ui-express';
+import jsonRefParser, {JSONSchema} from '@apidevtools/json-schema-ref-parser';
+
+
+// modifies the normal swagger-ui-express package
+// usage: app.use('/api', api.serve(), api.setup());
+// the paths property can be split using allOf
+// further route documentation can be included in the x-doc property
+
+export default class api {
+  static serve () {
+    return swagger.serve;
+  }
+
+  static setup () {
+    let apiDoc: JSONSchema = {};
+    jsonRefParser.bundle('api/api.yaml', (err, doc) => {  // parse yaml
+      if(err) throw err;
+      apiDoc = doc;
+      apiDoc.paths = apiDoc.paths.allOf.reduce((s, e) => Object.assign(s, e));  // bundle routes
+      apiDoc = this.resolveXDoc(apiDoc);
+      swagger.setup(apiDoc);
+    });
+    return swagger.setup(apiDoc, {customCssUrl: '/static/styles/swagger.css'})
+  }
+
+  private static resolveXDoc (doc) {  // resolve x-doc properties recursively
+    Object.keys(doc).forEach(key => {
+      if (doc[key] !== null && doc[key].hasOwnProperty('x-doc')) {
+        doc[key].description += this.addHtml(doc[key]['x-doc']);
+      }
+      else if (typeof doc[key] === 'object' && doc[key] !== null) {  // go deeper into recursion
+        doc[key] = this.resolveXDoc(doc[key]);
+      }
+    });
+    return doc;
+  }
+
+  private static addHtml (text) {  // add docs HTML
+    return '<details class="docs"><summary>docs</summary>' + text + '</details>';
+  }
+}

src/index.ts

@@ -1,9 +1,8 @@
 import express from 'express';
 import bodyParser from 'body-parser';
-import swagger from 'swagger-ui-express';
-import jsonRefParser, {JSONSchema} from '@apidevtools/json-schema-ref-parser';
 import contentFilter from 'content-filter';
 import mongoSanitize from 'mongo-sanitize';
+import api from './api';
 import db from './db';
 
 
@@ -55,14 +54,7 @@ app.use('/', require('./routes/condition'));
 app.use('/static', express.static('static'));
 
 // Swagger UI
-let apiDoc: JSONSchema = {};
+app.use('/api', api.serve(), api.setup());
-jsonRefParser.bundle('api/api.yaml', (err, doc) => {
-  if(err) throw err;
-  apiDoc = doc;
-  apiDoc.paths = apiDoc.paths.allOf.reduce((s, e) => Object.assign(s, e));
-  swagger.setup(apiDoc, {defaultModelsExpandDepth: -1, customCss: '.swagger-ui .topbar { display: none }'});
-});
-app.use('/api', swagger.serve, swagger.setup(apiDoc, {customCssUrl: '/static/styles/swagger.css'}));
 
 app.use((req, res) => {  // 404 error handling
   res.status(404).json({status: 'Not found'});

static/styles/swagger.css

@@ -52,6 +52,23 @@ body:after {
   font-family: "Bosch Sans", sans-serif;
 }
 
+/*custom docs*/
+.docs {
+  position: relative;
+  font-size: 14px;
+}
+
+.docs > summary {
+  position: absolute;
+  right: 0;
+  top: -25px;
+  cursor: pointer;
+}
+
+.docs-open:hover {
+  text-decoration: underline;
+}
+
 /*Remove topbar*/
 .swagger-ui .topbar {
     display: none