[WIP] add OpenAPI description and Swagger UI

package.json

@@ -115,6 +115,7 @@
     "spdy": "^4.0.0",
     "split": "^1.0.0",
     "stat-mode": "^1.0.0",
+    "swagger-ui-express": "^4.1.6",
     "unzipper": "^0.10.10",
     "uuid": "^8.1.0",
     "ws": "^7.0.0"
@@ -139,6 +140,7 @@
     "@types/semver": "^7.1.0",
     "@types/serialport": "^8.0.1",
     "@types/split": "^1.0.0",
+    "@types/swagger-ui-express": "^4.1.3",
     "chai": "^4.0.0",
     "chai-json-equal": "0.0.1",
     "chai-things": "^0.2.0",

src/apidocs/apidocs.ts

@@ -0,0 +1,23 @@
+import express from 'express'
+import swaggerUi from 'swagger-ui-express'
+import apidoc from './openapi.json'
+
+export interface OpenAPIPathsHandler {
+  addPaths: (paths: object) => void
+}
+
+export interface OpenAPIRootHandler {
+  setRootDoc: (root: object) => void
+}
+
+export function mountApiDocs(app: OpenAPIRootHandler & express.IRouter) {
+  app.get('/api-docs/openapi.json', (request, response) => {
+    response.json(apidoc)
+  })
+  app.use('/api-docs', swaggerUi.serve, swaggerUi.setup(undefined , {
+    swaggerOptions: {
+      url: '/api-docs/openapi.json'
+    }
+  }))
+  return app.setRootDoc(apidoc)
+}

src/apidocs/openapi.json

@@ -0,0 +1,14 @@
+{
+  "openapi": "3.0.2",
+  "info": {
+    "title": "Signal K http API (incomplete)",
+    "version": "1.x",
+    "description": ""
+  },
+  "servers": [
+    {
+      "url": "http://localhost:3000/signalk/v1/api/"
+    }
+  ],
+  "paths": {}
+}

src/config/config.js

@@ -26,6 +26,11 @@ const DeltaEditor = require('../deltaeditor')
 
 let disableWriteSettings = false
 
+//use dynamic path so that ts compiler does not detect this
+//json file, as ts compile needs to copy all (other) used
+//json files under /lib
+const packageJson = require('../../' + 'package.json')
+
 function load(app) {
   app.__argv = process.argv.slice(2)
   app.argv = require('minimist')(app.__argv)
@@ -40,14 +45,13 @@ function load(app) {
   debug('appPath:' + config.appPath)
 
   try {
-    const pkg = require('../../package.json')
-    config.name = pkg.name
-    config.author = pkg.author
-    config.contributors = pkg.contributors
-    config.version = pkg.version
-    config.description = pkg.description
-
-    checkPackageVersion('@signalk/server-admin-ui', pkg, app.config.appPath)
+    config.name = packageJson.name
+    config.author = packageJson.author
+    config.contributors = packageJson.contributors
+    config.version = packageJson.version
+    config.description = packageJson.description
+
+    checkPackageVersion('@signalk/server-admin-ui', packageJson, app.config.appPath)
   } catch (err) {
     console.error('error parsing package.json', err)
     process.exit(1)
@@ -442,5 +446,6 @@ module.exports = {
   writeDefaultsFile,
   readDefaultsFile,
   sendBaseDeltas,
-  writeBaseDeltasFile
+  writeBaseDeltasFile,
+  package: packageJson
 }

src/index.js

@@ -22,6 +22,7 @@ if (typeof [].includes !== 'function') {
 const express = require('express')
 const _ = require('lodash')
 const debug = require('debug')('signalk-server')
+const openApiDebug = require('debug')('signalk-server:openapi')
 const DeltaCache = require('./deltacache')
 const path = require('path')
 const http = require('http')
@@ -65,6 +66,15 @@ function Server(opts) {
 
   startSecurity(app, opts ? opts.securityConfig : null)
 
+  app.setRootDoc = (openApiRootDoc) => {
+    openApiDebug(`Setting root doc as ${JSON.stringify(openApiRootDoc)}`)
+    app.openApiRootDoc = openApiRootDoc
+  }
+  app.addPaths = (paths) => {
+    openApiDebug(`Add openAPI paths ${JSON.stringify(paths)}`)
+    app.openApiRootDoc.paths = {...paths, ...app.openApiRootDoc.paths}
+  }
+
   require('./serverroutes')(app, saveSecurityConfig, getSecurityConfig)
   require('./put').start(app)
 

src/interfaces/plugins.ts

@@ -29,6 +29,7 @@ import _ from 'lodash'
 import path from 'path'
 import { SERVERROUTESPREFIX } from '../constants'
 import { listAllSerialPorts, Ports } from '../serialports'
+import { OpenAPIPathsHandler } from '../apidocs/apidocs'
 
 // tslint:disable-next-line:no-var-requires
 const modulesWithKeyword = require('../modules').modulesWithKeyword
@@ -69,6 +70,7 @@ interface PluginInfo extends Plugin {
   id: string
   schema: () => void | object
   uiSchema: () => void | object
+  openApiPaths?: () => object
   version: string
   description: string
   state: string
@@ -658,6 +660,11 @@ module.exports = (theApp: any) => {
     }
     app.use(backwardsCompat('/plugins/' + plugin.id), router)
 
+    const openApiPathsHandler = app as OpenAPIPathsHandler
+    if (typeof plugin.openApiPaths === 'function') {
+      openApiPathsHandler.addPaths(plugin.openApiPaths())
+    }
+
     if (typeof plugin.signalKApiRoutes === 'function') {
       app.use('/signalk/v1/api', plugin.signalKApiRoutes(express.Router()))
     }

src/interfaces/rest.js

@@ -20,6 +20,7 @@ const { getMetadata, getUnits } = require('@signalk/signalk-schema')
 const ports = require('../ports')
 const geolib = require('geolib')
 const _ = require('lodash')
+const pkg = require('../config/config').package
 
 const iso8601rexexp = /^(-?(?:[1-9][0-9]*)?[0-9]{4})-(1[0-2]|0[1-9])-(3[01]|0[1-9]|[12][0-9])T(2[0-3]|[01][0-9]):([0-5][0-9]):([0-5][0-9])(\.[0-9]+)?Z$/
 
@@ -187,4 +188,4 @@ module.exports = function(app) {
   }
 }
 
-const getVersion = () => require('../../package.json').version
+const getVersion = () => pkg.version

src/serverroutes.js

@@ -38,6 +38,7 @@ const ncp = require('ncp').ncp
 const defaultSecurityStrategy = './tokensecurity'
 const skPrefix = '/signalk/v1'
 import { SERVERROUTESPREFIX } from './constants'
+import { mountApiDocs } from './apidocs/apidocs'
 
 module.exports = function(app, saveSecurityConfig, getSecurityConfig) {
   let securityWasEnabled
@@ -976,4 +977,6 @@ module.exports = function(app, saveSecurityConfig, getSecurityConfig) {
       })
     })
   })
+
+  mountApiDocs(app)
 }

tsconfig.json

@@ -5,7 +5,9 @@
     "outDir": "./lib",
     "esModuleInterop": true,
     "strict": true,
-    "allowJs": true
+    "allowJs": true,
+    "resolveJsonModule": true,
+    "rootDir": "./src"
   },
   "include": ["./src/**/*"],
   "exclude": ["node_modules"],